axis

# Axis: one coordination board for your whole team's agents

Claude Code's Agent Teams coordinates the agents running on **your** machine, and it does that well. Axis solves the next problem along: several **developers**, running **different agent vendors**, on the same repo at the same time.

Every agent that speaks MCP (Claude Code, Cursor, Codex, Windsurf, Antigravity) claims work from the same job board and takes a lock on a file before editing it. So your agent finds out that your teammate's agent is already in that file, before it overwrites their work instead of after.

If you are one developer on one machine, use Agent Teams. It is free, native, and better at that. Axis is for when the collisions stop being yours.

## See it in 30 seconds

```bash
bun examples/two-agent-collision.ts
```

Runs fully offline against a throwaway repo in your temp directory. Two agents go
for the same file; every status below is a real return value, not staged output:

```
2. Dana's agent (Claude Code) claims the top job and takes the file
   claim_next_job      -> CLAIMED  refactor auth to issue JWTs
   propose_file_access -> GRANTED  src/auth.ts

3. Sam's agent (Cursor, different machine) goes for the same file
   propose_file_access -> REQUIRES_ORCHESTRATION

File 'src/auth.ts' is locked by 'dana-claude-code' for: "refactor auth to issue
JWTs instead of session cookies". Pick a different file or job, or coordinate via
update_shared_context. The lock auto-expires after 30 min; use force_unlock only
if 'dana-claude-code' has crashed.

4. So it takes the other job instead of colliding
   claim_next_job      -> CLAIMED  add rate limiting to the login route
```

That denial is the whole product. Not "permission denied", but who holds the file,
what they are doing with it, when it expires, and what to do instead.

## "Why not just use git worktrees?"

Worktrees are the right tool and we use them. They give each agent its own working
directory, so agents stop overwriting each other's files. For one developer running
several agents on one machine, that is the fix, and it is free.

They do not reach across machines. Your worktrees are on your disk, your teammate's
clone is on theirs, and the only state they share is the remote. Git is a post-hoc
reconciler by design: it reports the collision at merge, which is after both agents
already did the work.

They also isolate files rather than intent. Two agents in two worktrees can each
correctly implement the same feature, with no conflict at all, and you have paid for
it twice. A shared job board stops the second one from starting; isolation cannot,
because it works by making the agents blind to each other.

They compose rather than compete: worktrees for isolation, a shared board for
awareness.

> ### Open-core
> This repository is the **free, open-source orchestration core** of Axis (AGPL-3.0): the MCP server, the `axis` CLI, the Python SDK, and the agent protocol — everything your agents use to coordinate.
>
> - **Free forever:** the orchestration layer — job board, file locking, shared notepad, sessions, project soul. It's just coordination state; it costs nothing to run.
> - **Paid (hosted):** the intelligence layer — hosted search (vector + full-text + trigram, fused and LLM-reranked), cited multi-hop `deep_search`, and incremental indexing — plus the managed backend, dashboard, and billing. The local server's `search_codebase` is ripgrep plus a keyword ranker (no index needed); a Pro key blends hosted results in when they arrive within budget. That lives at **[useaxis.dev](https://useaxis.dev)** (closed source) because it carries real embedding/LLM cost.
>
> **Quickest start:** sign up at [useaxis.dev](https://useaxis.dev), then point your MCP client at `https://useaxis.dev/api/mcp` and authenticate — no key to paste. See **[agent-instructions/mcp-setup.md](agent-instructions/mcp-setup.md)** for OAuth, API-key, and local-install options.

## Features

1.  **Shared job board**: Post work, claim it atomically. Claims run through `SELECT ... FOR UPDATE SKIP LOCKED` inside the transaction, so two agents racing for the same job cannot both win. Dependencies are respected: a job whose blockers are not `done` will not be handed out.
2.  **Per-file locks, tamper-evident**: An agent takes a lock before editing. Locks are advisory by nature (a coordination server cannot block a write it does not perform), so Axis records a content fingerprint when the lock is granted and lets the holder verify before writing. You find out that a file changed under you, instead of silently clobbering it.
3.  **One board across people and vendors**: Commit an org pin in `.axis/axis.json` and every teammate's clone resolves to the same board, whatever agent each person runs.
4.  **Live board and shared notepad**: See what every agent on the repo is doing right now at [useaxis.dev/team/board](https://useaxis.dev/team/board), pushed over Postgres Realtime.
5.  **MCP native**: Standard protocol and OAuth, so there is no key to paste and no plugin to install per client.

## Environment

Create a `.env.local` file for local development (see `.env.local.example`):

```
SHARED_CONTEXT_API_URL=http://localhost:3000
SHARED_CONTEXT_API_SECRET=your_shared_secret
OPENAI_API_KEY=your_openai_key
SUPABASE_URL=your_supabase_url
SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key
```

Do NOT set `PROJECT_NAME` unless you deliberately want to override detection:
it outranks repo detection, so a fixed value (like `default`) collapses every
repo on the machine onto one shared job board. Left unset, the project name is
derived from your repo (committed `.axis/axis.json` `"project"`, else the repo
folder name), so every clone of the same repo resolves the same board.

### Team coordination (shared boards)

Commit an org pin so every teammate's clone lands on the same board:

```json
// .axis/axis.json (at the repo root)
{ "project": "your-repo", "org": "<your org id from useaxis.dev/team>" }
```

Per-machine override: `AXIS_ORG_ID=<org id>`. Without an org, coordination
scopes to your personal workspace (solo behavior, unchanged). Watch and drive
the live board at `useaxis.dev/team/board`.

## Setup

1.  **Install Dependencies**:
    ```bash
    bun install
    ```

2.  **Initialize Context**:
    ```bash
    bun cli init
    ```

3.  **Start MCP Server**:
    To run the server locally for testing/connection:
    ```bash
    bun start:local
    ```
  This stdio server exposes the full Nerve Center toolset (job board, locks, notepad).
    Running from a checkout is for **contributing to Axis itself** — users connect
    to the hosted server instead (next paragraph).

    *Address for MCP Clients*: point your agent at the hosted MCP server — no
    install, no updates to manage:
    ```
    https://useaxis.dev/api/mcp
    ```
    Authenticate via OAuth or a Bearer API key; see
    [agent-instructions/mcp-setup.md](agent-instructions/mcp-setup.md).

    Axis derives project identity from the active repository. Supported agent
    hosts can provide `AXIS_WORKSPACE_ROOT`, `SUPERSET_WORKSPACE_PATH`, or
    `SUPERSET_ROOT_PATH`; these per-session values override a stale positional
    root in global MCP config so project souls, jobs, and locks cannot leak
    across repository switches. Set `AXIS_PROJECT_NAME` only when a project
    name must intentionally remain fixed across workspace changes.

Workspace switching is **automatic**: every tool call re-resolves the
workspace from the runtime hints and from any absolute file path in the
call's arguments. When either points at a different repository, the server
rebinds itself in-process and notes the switch in the tool response — no
restart, no stale "default" board. `switch_project` remains available for
explicit switches.

4.  **CLI Usage**:
    ```bash
    # Add an entry to activity.md
    bun cli add-context "Refactored the API to use Hono"
    ```

## Parallelism Philosophy

The key to Axis is the **Parallel Sprints**. You no longer have to manage a single agent sequentially; instead, you orchestrate a swarm.

1.  **Define the Objective**: Tell any agent (the "Manager"): "Build the Authentication System."
2.  **Autonomous Partitioning**: The agent decomposes the objective into jobs (API, UI, Tests) and posts them to the **Distributed Job Board**.
3.  **Horizontal Scaling**: You open Cursor, Claude Code, and Antigravity. They all instantly "claim" the next available job on the board.
4.  **Synchronized Execution**: While agents work in parallel, they stay in sync via the **Live Notepad**, ensuring that if one agent changes an API signature, the others adjust their code in real-time.

### Connecting Agents (MCP)
Point your IDE (Claude Desktop, Cursor, etc.) at the hosted MCP server:
```json
{
  "mcpServers": {
    "axis": {
      "url": "https://useaxis.dev/api/mcp"
    }
  }
}
```
Authenticate via OAuth (no key to manage) or a Bearer API key — see [agent-instructions/mcp-setup.md](agent-instructions/mcp-setup.md). New tools land server-side, so there is nothing to update on your machine.

### MCP Tooling
The server exposes 28 tools to agents. `src/shared/tool-manifest.ts` is the
canonical list and is what the test suite checks the server against; this section
is a readable summary of it.

**Coordination (free, open-core):**

- `get_project_soul` — load project context, goals, and conventions
- `update_project_soul` — write or refresh the project soul
- `post_job` — add a job to the distributed Job Board
- `list_jobs` — inspect status, priority, ownership, and dependencies
- `claim_job` — atomically claim a specific ticket
- `claim_next_job` — atomically claim the next available job
- `complete_job` — report a job outcome and release its file locks
- `cancel_job` — withdraw a posted job
- `propose_file_access` — pessimistically lock files before editing; pass `filePaths` to lock a multi-file batch in one call (all-or-nothing)
- `list_locks` — inspect active file ownership and i