Cartographer developer setup

Prerequisite: Node 22+ — the bundle is pure JS + WASM run by your Node. No native binaries, no repo access, no pnpm, no build.

curl -fsSL https://api.anchoragelabs.dev/cli/install.sh | sh

irm https://api.anchoragelabs.dev/cli/install.ps1 | iex

What the installers do: verify the download against the release’s published sha256, install to ~/.cartographer/current (versioned dirs, previous installs kept), and put a cartographer launcher on your PATH (~/.local/bin on Unix; a cartographer.cmd shim + user-PATH entry on Windows — open a new terminal after the Windows install).

cartographer --help    # verify the install

One token authenticates the CLI, the shared graph, and the hosted MCP:

1. 1.Open https://api.anchoragelabs.dev → Sign in with GitHub (org-gated — you must be an approved org member).
2. 2.Account → reveal token. Copy it and export it:

export ANCHORAGE_API_TOKEN=anch_yourname_xxxxxxxx
# Windows PowerShell:  $env:ANCHORAGE_API_TOKEN = "anch_yourname_xxxxxxxx"

cd <your-repo>
cartographer pull        # org's latest graph for this repo → local index
cartographer status      # three axes: your tree / your index / the hosted head

status tells you where you stand against the org graph: FRESH (in sync), AHEAD (you have unpushed structure), BEHIND (pull), DIVERGED (pull, re-index, push). Working on a repo you haven’t cloned? Pull it anyway:

cartographer pull --out ~/graphs/aleph --repo your-org/aleph
cartographer impact getUser ~/graphs/aleph --shared   # query with NO source tree

(--shared serves the pulled snapshot as-is — a normal query would rescan the empty dir and prune it.)

cartographer init                    # first time in a repo: facts + symbol index
cartographer watch                   # keep the index current while you edit
cartographer impact startRun         # blast radius: defs, refs, dependents, tests
cartographer refs startRun           # definitions + every reference
cartographer tests-for src/store.ts  # which tests cover this file
cartographer log                     # org graph history: who pushed what, when
cartographer graph-diff <idA> <idB>  # structural delta between two snapshots

Every query delta-refreshes the index first, so results always reflect your working tree. The index is a gitignored SQLite file (.anchorage/index/symbols.db) — nothing leaves your machine until you push.

cartographer push        # snapshot your index → org graph `latest`

Push is safe by default: it’s an immutable snapshot plus a compare-and-swap ref advance. If a teammate (or the Anchorage worker) pushed since you last synced, you get a 409 naming the current head — never a silent overwrite:

push rejected: your-org/x latest advanced to g8c1e… (commit 4fa1b2c9, by …)
fix: cartographer pull   # then re-index and push
    or: cartographer push --force-with-lease=g8c1e…

Re-pushing identical content is a no-op (“up to date”, zero bytes uploaded).

Two servers, one token:

• Hosted MCP — https://mcp.anchoragelabs.dev/mcp. Zero install. Tools: graph_lookup, graph_log, plus the Anchorage run tools (submit_run, wait_for_run, review_pr, …).
• Local MCP — the installed CLI serves your checkout with the full 10-tool set (repo_map, find_references, impact, locate_change, tests_for, symbol_outline, repo_facts, repo_context, context_for_task, graph_status). Start it with:

CARTOGRAPHER_MCP_DEV_TOKEN=pick-a-secret cartographer mcp --port 3100
# your agent then sends:  Authorization: Bearer pick-a-secret

Below: exact install per agent. ${ANCHORAGE_API_TOKEN} must be exported in the environment the agent starts from. For the local server, swap the URL for http://localhost:3100/mcp and the token for your CARTOGRAPHER_MCP_DEV_TOKEN.

Claude Code

Create (or extend) .mcp.json at the repo root — or ~/.claude.json for all projects:

{
  "mcpServers": {
    "anchorage": {
      "type": "http",
      "url": "https://mcp.anchoragelabs.dev/mcp",
      "headers": { "Authorization": "Bearer ${ANCHORAGE_API_TOKEN}" }
    }
  }
}

claude.ai (web)

Settings → Connectors → Add custom connector → https://mcp.anchoragelabs.dev/mcp. The browser opens a Connect Anchorage page — paste your API token once (OAuth handles the rest).

Cursor

~/.cursor/mcp.json (global) or .cursor/mcp.json (per repo):

{
  "mcpServers": {
    "anchorage": {
      "url": "https://mcp.anchoragelabs.dev/mcp",
      "headers": { "Authorization": "Bearer ${ANCHORAGE_API_TOKEN}" }
    }
  }
}

Codex

~/.codex/config.toml — newer Codex speaks HTTP MCP directly:

[mcp_servers.anchorage]
url = "https://mcp.anchoragelabs.dev/mcp"
http_headers = { Authorization = "Bearer ${ANCHORAGE_API_TOKEN}" }

Gemini CLI

~/.gemini/settings.json:

{
  "mcpServers": {
    "anchorage": {
      "httpUrl": "https://mcp.anchoragelabs.dev/mcp",
      "headers": { "Authorization": "Bearer ${ANCHORAGE_API_TOKEN}" }
    }
  }
}

GitHub Copilot (VS Code)

.vscode/mcp.json in the workspace (the inputs entry prompts once for the token and stores it outside the repo — never hard-code it here):

{
  "inputs": [
    { "type": "promptString", "id": "anchorage-token",
      "description": "Anchorage client token", "password": true }
  ],
  "servers": {
    "anchorage": {
      "type": "http",
      "url": "https://mcp.anchoragelabs.dev/mcp",
      "headers": { "Authorization": "Bearer ${input:anchorage-token}" }
    }
  }
}

OpenCode

opencode.json (repo) or ~/.config/opencode/opencode.json:

{
  "mcp": {
    "anchorage": {
      "type": "remote",
      "url": "https://mcp.anchoragelabs.dev/mcp",
      "enabled": true,
      "headers": { "Authorization": "Bearer ${ANCHORAGE_API_TOKEN}" }
    }
  }
}

Any stdio-only agent (fallback)

Bridge stdio ↔ HTTP with mcp-remote:

{
  "mcpServers": {
    "anchorage": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.anchoragelabs.dev/mcp",
               "--header", "Authorization: Bearer ${ANCHORAGE_API_TOKEN}"]
    }
  }
}

Support matrix

cartographer status --json   # with ANCHORAGE_API_TOKEN exported

Healthy output has "fresh": true (tree vs index) and a "remote": { "freshness": "fresh" | "ahead" | … } block (index vs org graph). If the remote block is missing, your token isn’t exported.

Installing the plugin gives agents the tools; the skill makes them use the graph instead of grepping. Paste the contents of anchorage-agent-skill.md into each agent’s instructions:

The skill is Cartographer-scoped: sync-before-work, graph-before-grep tool selection, mandatory impact / tests_for before changing public symbols, 409/lease recovery, version-stamped answers, and honesty/fallback rules.

Core queries are zero-token. Two optional commands call a model: cartographer narrate (plain-language repo summary) and cartographer map --llm (architecture claims). Configure your own key:

export ANCHORAGE_LLM_PROVIDER=anthropic      # anthropic · openai · openai-compatible · bedrock
export ANCHORAGE_LLM_API_KEY=sk-ant-...       # your own key — BYO, never shared
export ANCHORAGE_LLM_MODEL=claude-sonnet-4-6

Daily: pull → work (impact / refs / tests-for, agent tools) → push. Keep cartographer watch running during long sessions.