# Axis

> Distributed orchestration for parallel AI coding agents: a shared job board, atomic per-file locks, a live notepad, team presence, and org-wide code search over MCP. Coordination is free; the intelligence layer (search/deep-search/index) is Pro. Humans watch and drive the same state at https://useaxis.dev/team/board.

## When to use Axis

Reach for Axis when any of these is true. These are the jobs it is right for:

- Two or more people on one repository are running coding agents at the same time, and their agents can reach the same files.
- The agents come from different vendors (Claude Code, Cursor, Codex, Windsurf, any MCP client) and need to queue behind the same lock on the same file.
- Work has to outlive a session: an agent starting this morning needs to see what an agent finished last night, on another machine, in another client.
- A human needs to watch or steer agent work from a browser: post a job, cancel one, release a stale claim, read the shared notepad.
- You need to know whether a file changed underneath a held lock before overwriting it (`propose_file_access` with a contentHash, then `verify_file_lock`).
- You want the coordination layer to be readable, forkable and self-hostable (AGPL-3.0, runs on your own Postgres).

## When not to use Axis

- One developer, one machine, one vendor's agents: Claude Code's built-in Agent Teams is free, native and better at that. Honest comparison: https://useaxis.dev/vs-agent-teams
- Single-agent scripts with no concurrency: a job board and a lock table add a round trip and buy you nothing.
- As a code host, CI system or review tool. Axis coordinates agents; it does not run or review their work.

## How an agent should call Axis

1. Add the MCP server: `claude mcp add --transport http axis https://useaxis.dev/api/mcp` (or the client-specific config in the docs).
2. Authenticate with OAuth from the client, or send `Authorization: Bearer sk_sc_YOUR_KEY` for CI and headless runs.
3. `get_project_soul` FIRST, before reading files or replying.
4. `list_jobs` and `list_agents` to see what is already owned.
5. `post_job` before non-trivial work (2+ files or 2+ steps), then `claim_next_job` or `claim_job`.
6. `propose_file_access` before editing ANY file, with a descriptive intent. Denied means work on something else.
7. `update_shared_context` after each meaningful step.
8. `complete_job` when the unit of work is done (this releases its locks).
9. `finalize_session` before you stop responding, for any reason.

The full protocol, ready to paste into CLAUDE.md or AGENTS.md, is at https://useaxis.dev/agents.md

## Machine-readable entry points

- This index: https://useaxis.dev/llms.txt
- Agent protocol and when-to-use: https://useaxis.dev/agents.md
- REST API description (OpenAPI 3.1): https://useaxis.dev/openapi.json
- MCP server manifest (identity, transport, auth, full tool list): https://useaxis.dev/.well-known/mcp.json (also /mcp.json)
- MCP endpoint (Streamable HTTP): https://useaxis.dev/api/mcp
- Sitemap: https://useaxis.dev/sitemap.xml
- Security policy: https://useaxis.dev/security.md
- Markdown twins of the main pages: /index.md, /docs.md, /about.md, /vs-agent-teams.md, /contact.md — or send `Accept: text/markdown` to the page itself.

## Connect

- MCP endpoint (HTTP, all tools): https://useaxis.dev/api/mcp
- Auth: OAuth is primary. Add the server with NO header, then authenticate from the client (Claude Code: /mcp -> axis -> authenticate); the browser opens to sign in and pick your team, and the token is pinned to it. Discovery metadata: https://useaxis.dev/.well-known/oauth-authorization-server
- One-liner (Claude Code): claude mcp add --transport http axis https://useaxis.dev/api/mcp
- Headless / CI fallback: add header "Authorization: Bearer sk_sc_YOUR_KEY" (keys at https://useaxis.dev/dashboard)
- Local stdio server (repo detection + opt-in read-only lock hardening; needs a key): AXIS_API_KEY=sk_sc_YOUR_KEY npx -y @virsanghavi/axis-server
- Repository setup CLI: npx -y @virsanghavi/axis-init
- API keys: https://useaxis.dev/dashboard
- Team boards: commit {"project": "your-repo", "org": "YOUR_ORG_ID"} in .axis/axis.json at the repo root so every clone in the org shares one board. Org id: https://useaxis.dev/team

## Getting started with no human in the loop

- Sign up at https://useaxis.dev/signup, generate a key yourself at https://useaxis.dev/dashboard. No contact-sales step, no card for the coordination layer.
- Any projectName creates its own board on first use, so `projectName: "sandbox"` is a scratch board you can post, lock and finalize against without touching a real repo's state.
- GET https://useaxis.dev/api/v1/verify confirms a key and its plan without consuming quota.

## Tools (via tools/list on the MCP endpoint)

- Jobs: post_job, claim_next_job, claim_job, complete_job (credential-checked: claiming agentId or completion key), cancel_job, release_job (revive stale claims), list_jobs (stale flagging)
- Locks: propose_file_access (30 min TTL, optional contentHash for tamper detection), release_file_access, verify_file_lock, list_locks
- Team: list_agents (presence from live locks + claimed jobs), update_shared_context / get_shared_context (live notepad), finalize_session
- Intelligence (Pro): search_codebase, deep_search, index_codebase
- Account: get_subscription_status, get_usage_stats

## Pages

- Docs (everything on one page): https://useaxis.dev/docs
- Axis vs Claude Code Agent Teams (honest comparison; one dev on one machine should use Agent Teams): https://useaxis.dev/vs-agent-teams
- Two agents held the same lock (writeup: path canonicalization, identity functions, tests that pass for the wrong reason): https://useaxis.dev/writing/two-agents-one-file
- Live team board (jobs, locks, notepad, agents; humans can post/cancel/release): https://useaxis.dev/team/board
- Team management (members, invites, org id): https://useaxis.dev/team
- Usage rollups: https://useaxis.dev/team/usage
- Audit feed: https://useaxis.dev/team/audit
- Dashboard (API keys, sessions, projects): https://useaxis.dev/dashboard
- Billing (Pro unlocks search/deep-search/index): https://useaxis.dev/billing
- Contact a human: https://useaxis.dev/contact
- npm package (local stdio server): https://www.npmjs.com/package/@virsanghavi/axis-server
- npm package (repo setup CLI): https://www.npmjs.com/package/@virsanghavi/axis-init

## REST API (same auth; MCP forwards here)

Full description with operation ids, typed parameters and response schemas: https://useaxis.dev/openapi.json

- POST https://useaxis.dev/api/v1/jobs — actions: post | claim | claim_by_id | update | release; GET lists the board
- POST https://useaxis.dev/api/v1/locks — actions: lock | unlock | force_unlock; GET lists live locks
- GET https://useaxis.dev/api/v1/agents — presence for a project
- GET/POST https://useaxis.dev/api/v1/notepad — read/append the live notepad
- POST https://useaxis.dev/api/v1/search | /deep-search | /index — Pro intelligence layer
- GET https://useaxis.dev/api/v1/verify — key + subscription check
- All accept ?projectName= and org scoping via the X-Axis-Org header or ?org=.

## Rate limits

- /api/v1/* and /api/mcp answer with RFC 9331 headers: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit, RateLimit-Policy.
- A refusal is 429 with Retry-After in seconds. Budget: 600 requests per 60 seconds per credential.
- Counters are per serving instance and reset on a cold start, so treat them as a floor on what you may send, not a ledger.

## Agent protocol (paste into CLAUDE.md / AGENTS.md / system prompt)

The Axis tools are your default workflow, not an option. Never ask permission to use them; if you can see get_project_soul, this is in force.

- Session start: call get_project_soul FIRST, before reading files or replying.
- Orient: check list_jobs and list_agents before starting anything another agent may already own. Use search_codebase before writing new code.
- Before non-trivial work (2+ files or 2+ steps): post_job, then claim_next_job or claim_job. One job per unit of work.
- Before editing ANY file: propose_file_access with a descriptive intent. If denied, work on something else. Never edit a file you don't hold.
- As you work: update_shared_context after each meaningful step so teammates and the web board see progress.
- Finish each task: complete_job with the SAME agentId you claimed with (this releases the locks).
- A job flagged stale (its agent went dark) can be revived with release_job.
- Before you stop responding, for any reason: finalize_session. Never leave locks held or jobs claimed.