Cartograph — Full Guide

Cartograph is the Claude Code plugin that turns "I have a codebase" into "I have a living architecture board." Claude scans your code, detects the architecture, and pushes a structured graph — nodes and edges — to your board in the portal. No manual diagramming.

Cartograph connects as a Board Builder source: where OAuth sources (GitHub, Confluence) let the platform pull and interpret content, Cartograph does the analysis locally in your Claude Code session and pushes a ready-made graph.

Note

Everything the plugin does — /analyze, /sync, /insights — runs inside your Claude Code session and needs no model provider connected. Connecting a model is only for the portal's in-app Chat.

This is the complete reference. For a guided first run, see Quick Start; for a one-page overview, see Cartograph.

How Cartograph fits as a source

Board Builder is a source type in the Sources catalog. It authenticates with a token + secret (not OAuth) and receives a pre-structured graph the plugin built from your code. See Connecting Sources for the source model and the Board Builder API for the wire format underneath.

Prerequisites

• Claude Code installed and running
• A workspace with at least one board (your Root Board is created for you)
• A Board Builder source bound to that board — this is what gives you the Binding Token and API Secret

Get your credentials

1. In the portal: Sources → Add Source → Board Builder. Saving generates the API Secret (it starts with ck_cp_live_).
2. Open your board → Sources panel → Bind Source, select that Board Builder source, and set the branch (e.g. main).
3. From the binding, click Copy Credentials to grab the Binding Token and API Secret.

The config file

Cartograph reads .contextdx/config.json at the root of your repo:

{
  "bindingToken": "YWJjMTIz...",
  "apiSecret": "ck_cp_live_xxx",
  "branch": "main",
  "boardSlug": "my-project-overview"
}

Note

The secret prefix is ck_cp_live_. /configure offers to add .contextdx/ to your .gitignore — let it. Credentials never belong in version control.

Install

Add the marketplace once, then install the plugin:

/plugin marketplace add contextdx/cartograph-plugin
/plugin install cdx-code@cdx-plugins

Restart Claude Code after installing so the commands load. To scope the install, add --scope user (default), --scope project, or --scope local.

Note

cdx-code is the install name. Everywhere else — in docs and in the portal — the plugin is called Cartograph.

Connect — /configure

/configure

/configure reads .contextdx/config.json, validates it, tests the connection, and auto-discovers your Root Board (writing boardSlug for you). It reads credentials from the file rather than asking you to paste secrets inline, and offers to add .contextdx/ to your .gitignore.

Settle the vocabulary — /analyze-archetypes (Phase 1)

Cartograph runs a two-phase workflow. Phase 1 settles the archetype vocabulary — the set of component types your board uses — before Phase 2 describes the system. On a new codebase, run this first:

/analyze-archetypes

It scans for component patterns that don't fit your workspace's archetype catalogue and submits proposals for admin review, so every component lands on a fitting type instead of a misfit you'd have to re-type later. It's a precondition for /analyze: if the catalogue or your commit has drifted, /analyze prompts you to run it.

Map your architecture — /analyze (Phase 2)

/analyze

Claude scans your project — detecting services, APIs, databases, and queues — and maps how they connect into a structured graph (an L0 overview, usually 10–30 nodes, grouped into domains). It runs locally; nothing is pushed until you /sync.

Cartograph builds a drill-down hierarchy:

/analyze --drill <parent-board-slug>/<node-slug>   # create a child (L1/L2) board for one node
/analyze --all                                      # progressive pass across all layers, with review between levels
/analyze --clean                                    # full re-analysis from scratch

Analysis is incremental by default — it reads the git diff since the commit it last analyzed and only re-touches changed files. This applies to every mode. Use --clean when an incremental result looks stale.

Push to the portal — /sync

/sync

Your architecture appears as a visual diagram on your board: nodes for each component with their types and descriptions, edges showing imports, API calls, data access, and event flows.

/sync --board <slug>   # sync a specific board
/sync --all            # sync the entire layered tree

/sync defaults to a smart, diff-based merge: it pulls the board's current server state, computes what changed, and pushes only the difference. Plain /sync pushes one board (and prompts if you have several).

Source references

By default, every synced node and edge carries a source reference — the relative file path it was derived from, plus a navigable link into your git host when a remote is configured — and a node's description may include that path. This is what powers click-through from a board element back to the code.

Warning

Source references send your repository's file paths (and, with a git remote, links to specific files) to the portal. If those paths are sensitive, opt out by setting "includeSourceReferences": false in .contextdx/config.json — /sync then pushes nodes and edges with no file paths anywhere in the payload. Your local analysis files under .contextdx/boards/ keep the paths regardless, so you can turn this back on later and re-sync without re-analyzing.

Sync guardrails

Before any board reaches the portal, /sync runs a structural check. If a board has more than 8 nodes but no domain_group containers, the sync is rejected — flat boards at that size almost always mean the analyzer skipped grouping, and they render as an unreadable wall of nodes.

Expand

The fix is to re-run /analyze; the agent's protocol includes a domain-grouping step that populates domain_group containers automatically. If your project is genuinely small enough that a flat board is right, opt out in .contextdx/config.json:

{
  "validation": {
    "skipBoardStructureCheck": true
  }
}

Note

When disabled, every /sync prints a stderr notice ([cdx-sync] board-structure check disabled via config.validation.skipBoardStructureCheck) so the opt-out is never silent. Remove the field — or set it to false — to re-enable the check.

Run insights — /insights

/insights

Insight skills are defined by your workspace admin on the portal — security checks, quality reviews, dependency audits. The server defines what each skill looks for; Claude Code does the reasoning, reading the board and your source files locally, then pushing findings back. Each finding ties to a specific component and highlights the affected area on your diagram.

/insights find auth and data-access risks   # match a natural-language prompt to skills
/insights --select                           # choose skills and a focus interactively
/insights --list                             # list available skills
/insights security-analysis                  # run a specific skill by slug
/insights --all                              # run every skill

Note

/insights runs entirely in Claude Code — no model provider required. This is different from the portal's in-app "With Insights" mode, which runs through Chat and does need a connected model. The insights tab in the portal only displays results; the plugin generates them here.

Seed a demo — /demo-insights

/demo-insights [count] [--board <slug>] [focus prompt]

The showcase counterpart to /insights: it generates a small set (default 3, clamped 2–4) of path-rich insights, each tracing a legible path across multiple nodes — ideal for demos and screenshots. It reuses the same skills and push pipeline as /insights.

Check where things stand — /status

/status

Read-only. Shows your configuration, the archetype precondition state, the board manifest, per-board analysis summaries (node/edge counts by type), sync status, and the files changed since each board's last analysis.

Expand

All commands

What Cartograph writes

Everything lives under .contextdx/ at your repo root, and the plugin keeps that directory gitignored:

• config.json — your credentials and settings
• boards/manifest.json — the board registry (slugs, layers, parent-child links, node/edge counts)
• boards/<board-slug>.json — per-board analysis data
• boards/stores/<board-slug>.store.json — per-board sync state (element hashes) for smart diffing
• caches and an archetype lock file used by the two-phase workflow

A single SessionStart hook scaffolds config.json on first run and appends .contextdx/ to your .gitignore. There is no background auto-sync — analysis and sync happen only when you run the commands.

Supported languages

JavaScript/TypeScript, Python, Java, Go, C#/.NET, Ruby, and Rust. Cartograph analyzes application code — it does not analyze infrastructure-as-code (Terraform, CloudFormation, CDK).

Troubleshooting

What's next