ContextDX Plugins

The ContextDX plugins turn "I have a codebase" — or "I have a pile of docs" — into "I have a living board." The plugin scans your work locally, detects its structure, and pushes a structured graph — nodes and edges — to your board in the portal. No manual diagramming.

There are two, split by what they read:

Both emit the same node/edge model and sync through the same engine — only the analysis brain differs (services, APIs, and imports vs. concepts, decisions, and references). Everything below applies to both unless a note calls out a difference. Cdx Code runs on Claude Code, Codex, or Cursor; Cdx Work on Claude Code and Codex (Cursor coming).

Either plugin connects as a Code Plugin source: where OAuth sources (GitHub, Confluence) let the platform pull and interpret content, the plugin does the analysis locally in your AI coding session and pushes a ready-made graph.

Note

Everything the plugins do — /analyze, /analyze-docs, /sync, /insights — runs inside your own AI coding 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 Getting Started.

How the plugins fit as a source

Code Plugin 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 or docs. See Connecting Sources for the source model and the Boards API for the wire format underneath.

Prerequisites

• Claude Code, Codex, or Cursor installed and running
• A workspace with at least one board (your Root Board is created for you)
• A Code Plugin 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 → Code Plugin. Saving generates the API Secret (it starts with ck_cp_live_).
2. Open your board → Sources panel → Bind Source, select that Code Plugin 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

The plugin reads .contextdx/config.json at the root of your repo or document set:

{
  "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 for your platform, then install the plugin you want — cdx-code or cdx-work:

/plugin marketplace add contextdx/cdx-claude
/plugin install cdx-code@contextdx   # or cdx-work@contextdx

Note

cdx-code and cdx-work are the install ids — everything else, in the docs and the portal, calls them Cdx Code and Cdx Work.

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)

The plugins run a two-phase workflow. Phase 1 settles the archetype vocabulary — the set of node types your board uses — before Phase 2 describes the system. On a new codebase or document set, run this first:

/analyze-archetypes

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

Map your architecture — /analyze (Phase 2)

/analyze

The plugin 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.

Note

Mapping a document set instead? Run /analyze-docs (Cdx Work). It reads the same way but detects concepts, documents, decisions, and stakeholders rather than code, and takes the same flags below (--drill, --all, --clean).

It 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). /sync is shared by both plugins and behaves identically.

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 (or, for Cdx Work, back to the document).

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. (This guardrail applies to Cdx Code; Cdx Work groups by subject area instead.)

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; the plugin does the reasoning, reading the board and your source files locally, then pushing findings back. Each finding ties to a specific node 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 your AI coding session — 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

The operational commands — /configure, /status, /sync, /insights, /demo-insights, /help — are shared by both plugins and behave identically. Only the Phase 2 analysis command differs: /analyze (Cdx Code) vs. /analyze-docs (Cdx Work).

What the plugins write

Everything lives under .contextdx/ at the root of your repo or document set, 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.

What each plugin reads

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

Cdx Work analyzes a document set: Markdown/MDX, reStructuredText, AsciiDoc, plain text, wiki exports (Confluence, Notion), and PDFs — discovered across the usual locations (docs/, wiki/, rfcs/, adr/, specs/, policies/, notes/, root *.md).

Troubleshooting

What's next