Atlas Documentation

Atlas is a navigation manifest folder for multi-repo projects. It sits as a sibling to your product repos and tells AI agents three things:

1. Which repos belong to which product, so the agent doesn't get lost in 50 unrelated repos.
2. What context matters: glossary, decisions, active work, runbook.
3. Who's working on what right now, so parallel agents don't collide. Local SQLite-backed claim/release with TTL.

Atlas references repos by relative path. It never moves or copies them. Source code stays where it is; atlas is the cross-repo index.

From npm

npm install -g @cidx-dev/atlas
atlascli install

The first command puts the atlascli binary on your $PATH. The second copies the slash commands to ~/.claude/commands/.

From source

git clone https://github.com/cidx-dev/atlas.git
cd atlas
npm install
npm run build:cli
./install.sh

From the parent directory of your repos (the dir that contains all your sibling product repos), open Claude Code and run:

cd /path/to/your/projects
claude
> /atlas-init

The slash command surveys your sibling repos, proposes groupings based on naming patterns, asks you to confirm, then creates the atlas/ folder with everything wired up.

Important: Claude Code's working directory is fixed at session start. Launch from the parent dir, not from inside a single repo. cd after launch doesn't move the session.

What /atlas-init creates:

parent/
  atlas/
    META.yml              ← schema version + revision counter
    AGENTS.md             ← tells agents "this is a manifest, not source"
    README.md             ← top-level overview
    .claude/settings.json ← parent-dir access for sibling repos
    .gitignore
    .atlasignore          ← personal ignore list (gitignored)
    .runtime/             ← gitignored, local SQLite claims state
    <product>/
      atlas.yml           ← repos (relative paths), Linear, external refs
      README.md           ← purpose, glossary, runbook, decisions
      AGENTS.md           ← per-product agent guide
  repo_a/                 ← actual source code (referenced from atlas)
  repo_b/
  ...

The atlascli binary exposes all atlas operations:

Example claim

atlascli claim \
  --intent "fix prospect dedup bug" \
  --paths "core_lead_followups/src/sender.py,core_prospect_hub/src/api.ts" \
  --ttl 2h \
  --reason "duplicate sends in production"

If paths are already claimed by another agent, the CLI exits with code 2 and prints the conflicting claim.

Installed to ~/.claude/commands/ after running atlascli install. Slash commands cover human-driven inspection and walkthroughs. Claim and release are agent operations and live in MCP / CLI only.

Claim and release are agent operations. The agent itself runs them automatically, not the human.

# at task start
atlascli claim --intent "fix dedup" --paths "..." --ttl 2h

# at task end
atlascli release <claim-id>

The generated atlas/AGENTS.md contains the auto-claim instructions; agents landing in the atlas pick them up automatically.

atlasmcp exposes claim, release, status, extend, pause, resume, and rename as native MCP tools. Configure in your MCP client:

{
  "mcpServers": {
    "atlas": { "command": "atlasmcp" }
  }
}

Works with Claude Desktop, Cursor, OpenAI Codex, and any client that supports stdio MCP. The server uses the same SQLite store as the CLI. claims made via MCP are visible to atlascli status and vice versa.

Sometimes you want atlas out of the way for a while - solo experimental work, debugging, or a quick fix where coordination overhead isn't worth it. Pause makes atlas a no-op without uninstalling anything.

# pause for 30 minutes, also release current claims
atlascli pause --duration 30m --release-all --reason "experimental refactor"

# while paused, claim returns success without recording
atlascli claim --intent "..." --paths "..."
# → "atlas is paused, proceeding without claim"

# resume to re-enable coordination
atlascli resume

State persists at atlas/.runtime/pause.json with optional TTL. if you forget to resume, the pause auto-expires. MCP equivalents: atlas_pause, atlas_resume, atlas_pause_state.

Belt-and-suspenders against zombie claims. Add this to your .claude/settings.json (per-project or global) so claims auto-release when sessions end:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "atlascli release-all --silent || true"
          }
        ]
      }
    ]
  }
}

The --silent flag suppresses output; the || true ensures the hook never blocks session exit if the command fails.

Atlas tracks three independent versions, all visible via atlascli version:

The canonical schema lives in SCHEMA.md at the repo root. Structural changes bump the schema version; migration scripts (run via atlascli migrate, planned) bridge versions forward.

Every atlas.yml has a version: field. Manifests without one are treated as legacy and require migration. Adding optional fields is backward-compatible, since old readers ignore unknown keys.