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

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 (closed source) because it carries real embedding/LLM cost.

Quickest start: sign up at 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 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, 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:

// .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

   Copy

   bun install
   

2. Initialize Context:

   bash

   Copy

   bun cli init
   

3. Start MCP Server: To run the server locally for testing/connection:

   bash

   Copy

   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

   Copy

   # 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:

{
  "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. 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):