Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/virsanghavi/axis/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through connecting an AI coding agent to Axis and running your first coordinated workflow. You’ll use the hosted MCP endpoint at https://useaxis.dev/api/mcp — no package to install, no server to manage. By the end you’ll have an agent that claims jobs, locks files, and shares context with every other agent on your project.
1
Sign up at useaxis.dev
2
Create an account at useaxis.dev. Every account starts with the free coordination tier — job board, file locks, and the shared notepad — at no cost.
3
Once you’re signed in, the dashboard’s “Copy connect command” button generates the right connection snippet pre-filled with your API key. You can also use OAuth (no key required) — your MCP client opens the browser on first connect and handles token storage automatically.
4
Connect your agent to the hosted MCP endpoint
5
Point your agent at https://useaxis.dev/api/mcp. The server is HTTP MCP; every major agent client supports it directly.
6
Claude Code (recommended — OAuth, no key required):
7
claude mcp add --scope project --transport http axis https://useaxis.dev/api/mcp
8
After adding the server, open the MCP panel to authenticate:
9
claude /mcp    # select "axis" → Authenticate → log in in the browser
10
All other clients (Cursor, Windsurf, Codex, VS Code, Gemini CLI…):
11
{
  "mcpServers": {
    "axis": {
      "url": "https://useaxis.dev/api/mcp"
    }
  }
}
12
Omit the headers field to trigger OAuth login on first use. To authenticate with an API key instead, add:
13
{
  "mcpServers": {
    "axis": {
      "url": "https://useaxis.dev/api/mcp",
      "headers": { "Authorization": "Bearer sk_sc_your_key" }
    }
  }
}
14
For stdio-only clients (Cline, Zed, JetBrains, older Codex), bridge through mcp-remote:
15
{
  "mcpServers": {
    "axis": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://useaxis.dev/api/mcp"]
    }
  }
}
16
Project identity is derived automatically from the nearest .git or package.json walking up from the current directory, so each repo maps to its own Axis project without any configuration. Commit a .axis/axis.json to pin the project name so every teammate’s agents coordinate on the same board.
17
Initialize your project with axis-init
18
Run the init command at your repo root. This is a one-time setup that scaffolds the context and rule files Axis agents read on every session start.
19
npx axis-init@latest
20
axis-init creates the following structure:
21
.axis/
  axis.json                     # project config (project name, governance mode)
  instructions/
    context.md                  # project goals and architecture — edited by get_project_soul / update_project_soul
    conventions.md              # coding conventions and agent behavioral norms
    activity.md                 # activity log, appended by update_shared_context
  research/                     # shared documents and research artifacts

.cursorrules                    # Axis agent protocol for Cursor
CLAUDE.md                       # Axis agent protocol for Claude Code
.windsurfrules                  # Axis agent protocol for Windsurf
AGENTS.md                       # Universal protocol — Codex, Antigravity, and any other agent
22
The IDE rule files (.cursorrules, CLAUDE.md, .windsurfrules, AGENTS.md) embed the full Axis agent protocol so every connected agent automatically follows the coordination workflow — without any per-session prompting.
23
Commit .axis/axis.json, CLAUDE.md, .cursorrules, .windsurfrules, and AGENTS.md to version control. Every teammate’s agents will load them on startup and coordinate on the same project without per-machine configuration.
24
Ask your agent to call get_project_soul
25
Per the agent protocol, get_project_soul is the first action in every session — non-negotiable. It loads the project goals, architecture overview, and coding conventions from .axis/instructions/context.md and conventions.md. Every other action depends on this context.
26
When you connected in step 2, the IDE rule files you scaffolded in step 3 already instruct your agent to do this automatically. To verify it’s working, ask your agent:
27
“What are the goals and conventions for this project?”
28
Your agent will call get_project_soul, return the contents of your context files, and then be ready to start coordinated work.
29
If the context files are still blank templates (as scaffolded by axis-init), use update_project_soul to fill in your project’s goals, architecture, and conventions. Future agents — and teammates’ agents — will load this context at the start of every session.
30
Post your first job
31
Ask your agent to post a job to the board. Jobs are the atomic unit of work in Axis — claiming one is how agents stake their intent before editing code.
32
Ask your agent to run:
33
Post a job with title "Set up project conventions" and description "Fill in .axis/instructions/context.md with the project goals, stack, and architecture overview."
34
Under the hood, your agent will call post_job:
35
{
  "title": "Set up project conventions",
  "description": "Fill in .axis/instructions/context.md with the project goals, stack, and architecture overview.",
  "priority": "medium"
}
36
The job now lives on the shared board. Any agent — yours, a teammate’s, a different vendor — can call claim_next_job to atomically pick it up. Two agents racing for the same job cannot both win.

​
See Coordination in Action

The Axis repo ships a two-agent collision demo that 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: 
bun examples/two-agent-collision.ts

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.

​
Next Steps

Concepts

Understand the job board, file locks, shared notepad, and project soul in depth.

Connecting Agents

Detailed setup for Claude Code, Cursor, Windsurf, Codex, Gemini CLI, and Antigravity.

Build docs developers (and LLMs) love

Get started for freeTalk to us