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.

Axis needs to know two things before agents can coordinate as a team: which project board to use, and which org owns it. By default, Axis derives the project name from your repo directory — so every clone of the same repo lands on the same board without any configuration. Adding an org pin tells the server which team’s shared board to use, turning per-developer isolation into genuine multi-developer coordination. One committed file does both.
Without an org pin, each developer’s agents coordinate on their personal board. Teammates cannot see each other’s jobs or locks. Committing the org pin is required for true team coordination.

​
How Project Auto-Detection Works

When no explicit pin is set, Axis walks up the directory tree from the current working directory looking for the nearest .git directory or package.json. It uses the name of that directory as the project name. This means:
  • Every clone of github.com/acme/payments-api resolves to a project named payments-api by default
  • Forks, branches, and worktrees all resolve to the same board as the original clone
  • No configuration is needed for solo use — the right project is always selected
This heuristic is good enough for individuals. Teams need the org pin so that “the same project name” resolves to a shared board rather than each developer’s personal version of that name.

​
Committing the Pin

Create .axis/axis.json at the repository root and commit it: 
{
  "project": "your-repo",
  "org": "<your-org-id-from-useaxis.dev/team>"
}
Find your org ID on the team page. Once this file is committed, every developer who clones or pulls the repo will have their agents automatically resolve to the shared org board — no per-machine setup, no environment variables to distribute.

​
Field Reference

FieldTypeDescription
projectstringThe board name. Must be unique within the org. Defaults to the current directory name when created by axis-init.
orgstringThe org ID from useaxis.dev/team. Binds every agent on every machine to the same shared board.

​
What axis-init Creates

Running npx axis-init in your repo creates .axis/axis.json automatically, with project set to the current directory name: 
{
  "version": "1.0.1",
  "project": "my-repo-name",
  "governance": "strict"
}
The org field is not set by axis-init — add it manually after creating your org at useaxis.dev.

​
Per-Machine Override

If a developer needs to work against a different org (for example, a contractor working across multiple client orgs), they can set AXIS_ORG_ID in their environment: 
AXIS_ORG_ID=org_abc123
This overrides the org field in .axis/axis.json for that machine only. The committed file is unchanged and all other teammates continue to use the org it specifies.

​
The PROJECT_NAME Warning

Do not set PROJECT_NAME (or AXIS_PROJECT_NAME) unless you have a deliberate reason to pin a fixed project name. It outranks repository detection entirely — a fixed value like default collapses every repo on the machine onto one shared job board. This is the single most common cause of “why are another repo’s jobs on my board?”
Leave these variables unset in normal use. Axis will derive the correct project name from the repo directory and .axis/axis.json automatically.

​
Workspace Switching

Workspace switching is automatic. Every tool call re-resolves the workspace from two sources:
  1. Runtime hints provided by the agent host (AXIS_WORKSPACE_ROOT, SUPERSET_WORKSPACE_PATH, SUPERSET_ROOT_PATH)
  2. Absolute file paths present in the tool call’s arguments
When either source points at a different repository than the current one, the server rebinds itself in-process and notes the switch in the tool response. No restart is required. The switch_project tool is available for explicit switches on the local server only — it is not present on the hosted surface, where every call resolves its own workspace fresh from the call’s context. Set AXIS_PROJECT_NAME only when a project name must intentionally remain fixed across workspace changes — for example, a meta-orchestrator that always acts on behalf of one project regardless of where it runs.

​
Complete .axis/axis.json Structure

{
  "project": "your-repo",
  "org": "<your-org-id-from-useaxis.dev/team>"
}
FieldRequiredDescription
projectRecommendedThe board name within the org. Defaults to the repo directory name if omitted. Override only if you want a canonical name that differs from the folder name.
orgRequired for teamsThe org ID that scopes this project to a shared team board. Without this, each developer’s agents land on their own personal board.
This file should be committed to version control so it is present on every clone. It contains no secrets — only the org ID, which is not sensitive.

Build docs developers (and LLMs) love

Get started for freeTalk to us