ContextDX Plugins

The plugins are how your codebase and your boards stay in step. They run inside the AI coding agent you already use — Claude Code, Codex, or Cursor — and they don't try to replace it: your agent still reads and writes the code, while the plugin keeps track of the system that code adds up to.

That traffic runs both ways.

Up, from the code. The plugin analyses your project locally and builds a structured graph of services, APIs, databases, concepts, and how they connect. That graph becomes a living board — you never draw a diagram.

Down, to the coding session. The board sends back everything your app has learned about how it should be built: compiled skills, the intents someone authored on the board, unbuilt designs, and aspect contracts. Your agent implements against that context instead of guessing at it.

There are two plugins:

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 an OAuth source like Confluence lets 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 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.

The five lifecycle stages

The commands are organized into five stages — /help renders this same grouping, and /status opens with a lifecycle dial telling you which stage you're in and the one next command to run:

The stages form a loop, not a line: /monitor findings become insights an architect turns into intents; /build and /intents change the code; /analyze + /sync verify the change on the board; /insights evaluates the new state.

There are two starting points:

• Existing project? Start at Map — analyze and sync it onto a board.
• Empty repo bound to a platform app? Start at Build — /build implements the build context the platform already carries, and the first /analyze + /sync afterwards is what populates your board.

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 exchanges pre-structured data with the platform: it pushes graphs, findings, and aspect snapshots, and pulls archetypes, insight skills, compiled skills, intents, and aspect contracts. 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 — /login sets this up for you in the browser; only the manual /configure path needs you to copy credentials

The config file

The plugin reads .contextdx/config.json at the root of your repo or document set. /login writes it for you; for the manual path, get a Binding Token and API Secret from the portal (Sources → Add Source → Code Plugin — saving generates the secret) and create:

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

Note

For headless and scheduled runs (e.g. a /monitor schedule in a fresh clone), every credential field can come from the environment instead: CONTEXTDX_BINDING_TOKEN, CONTEXTDX_API_SECRET, CONTEXTDX_BOARD_SLUG, CONTEXTDX_BASE_URL. Env vars win over the file. Credentials never belong in version control — /login and /configure add .contextdx/ to your .gitignore.

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.

1 · Connect

Sign in — /login

/login

The no-copy-paste path: your browser opens the portal, you sign in, pick a workspace and board, and the plugin writes the full credential triple (bindingToken + apiSecret + boardSlug) into .contextdx/config.json itself. Already bound and want a different board? /configure offers a rebind flow that reopens the browser picker.

Manual setup — /configure

/configure

For hand-managed credentials and self-hosted instances: 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.

Both commands end by telling you the one next step for this repo — /analyze-archetypes for an existing project, /build for an empty repo whose platform app already carries compiled skills.

Where am I? — /status

/status

Read-only and offline. The first line is the lifecycle dial — e.g. connected, 6 compiled skill(s), repo is empty — next: /build, or connected → mapped, with drift — next: /analyze (incremental) then /sync. Below it: configuration, the archetype precondition state, the board manifest, per-board analysis summaries (node/edge counts by type), sync status, an analysis coverage section (Cdx Code) — how much of the repo your boards describe, what's pending, and which nodes have gone stale — adopted aspects, and the files changed since each board's last analysis.

Expand

2 · Map

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

Mapping runs 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 the system — /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.

Analysis coverage (Cdx Code)

How much of the repo does the board actually describe? Every /analyze answers that with a deterministic analysis coverage ledger: it inventories the repo's architectural source files — including agent-native artifacts (skills, slash-commands, and agent definitions written as frontmattered markdown, the architecture of modern AI-tooling repos) — records which node covers each one, and diffs that against everything that changed since the last analysis — uncommitted edits included. Every run ends on the coverage dashboard — a progress bar with the change since your previous run (▲ up from 62%) and a ranked Where to go next list — and then offers a choice: analyse one of the recommended areas now (stale boards first, then the biggest unanalysed directories), or stop and /sync what you have. The same dashboard appears in /status. The numbers it shows:

• % analysed — files genuinely analysed, over the architectural total. A file that's merely mapped — claimed by a drill-down candidate whose child board hasn't been built yet — doesn't count until that drill-down runs, so a high-level map can never masquerade as deep analysis. Folders you've chosen to ignore and files the analyzer explicitly waived as non-architectural sit outside the denominator, so glue code never drags the number down.
• Mapped, awaiting drill-down — files placed on the map under a node that declares a child board not yet built. The dashboard names each pending drill-down and how many files it would convert from mapped to analysed.
• Pending — files no node covers yet. A to-triage list, not a failure: it's the exact worklist the next /analyze picks up.
• Stale nodes — nodes whose files changed since the board last analysed them. This is the drift signal: the code moved, the board hasn't yet.

The ledger is what makes incremental analysis precise — /analyze re-touches exactly the stale nodes and pending files instead of re-deriving scope each run. A board analysed before coverage tracking reports coverage unknown until its next analysis records what each node covers.

Two optional config fields tune the ledger, both under a coverage key in .contextdx/config.json:

Note

Pending and stale file names never leave your machine — /sync reports only the counts to your board's hub. The full file-level detail stays in .contextdx/coverage.json.

Extract contracts — /adopt (Cdx Code)

/adopt --db     # extract the database schema aspect
/adopt --api    # extract the API surface aspect

Beyond nodes and edges, a board can carry aspects — structured snapshots of your database schema (tables, columns, keys, indexes) and API surface (endpoints, params, auth). /adopt extracts them from the code and reconciles them onto the bound board (--mode replace|merge); rows a human authored on the portal are never overwritten. These same snapshots come back down as contracts when /build materializes a design (see the Build stage below).

Inspect the running UI — /inspect (Cdx Code)

/inspect                          # open the running app; pick + annotate; record a session
/inspect --url http://localhost:3000
/inspect --capture <url>          # headless: screenshot + element map, no human
/inspect --list | --show <id>     # review recorded sessions

/inspect turns what you see into work the board can carry. It opens your running app in a real browser — your installed Chrome, driven over the DevTools protocol, nothing downloaded, on a throwaway profile — and gives you a small draggable toolbar:

• Browse (the default) — the page is fully interactive. Log in, open menus, navigate to the screen you care about; nothing is captured yet.
• Pick — hover to highlight a component, click to select it (with an optional note). It records the CSS selector, the accessibility role/name, the component name when it can detect one, and correlates the route to a ui.page on your board.
• Annotate — drag a box over a region and add a note ("this should be a dropdown"). Esc or clicking the armed button returns you to Browse.

Each session is saved locally under .contextdx/inspections/<id>/ — clean screenshots plus the structured metadata — and needs no credentials to capture; only sharing it back does. When you're done, /inspect asks what the session should become:

• Propose a new intent — draft a work item from your notes, anchored to the ui.page you captured.
• Attach to an intent you're working on — add the session as visual evidence to a claimed intent.
• Keep it local — just the screenshots and a readout of what each pick maps to in code.

Then, once you're connected, it offers to push — telling you exactly what leaves the machine (the environment name and the captured URLs) and confirming once. Pushing does two things: the intent's screenshots become visual context an architect can annotate, and each correlated page's clean screenshot + element map is stored on its ui.page as a page capture — the board's live picture of that screen.

Note

No local browser — a cloud or headless session? /inspect --capture <url> takes the shot and records the element map without a human, so the capture path still works where a window can't open.

Expand

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. It's also what verifies intents: when a push matches a change an intent proposed, the server stamps it verified (see /intents under the Build stage).

After a successful push, /sync (Cdx Code) also reports the repo's analysis coverage snapshot — counts only, never file paths — which is what feeds the coverage card on your app board's hub, and tells you where coverage stands (naming the next /analyze when there's still a gap). A platform that predates coverage support is skipped silently; the sync itself never fails over it.

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.

Seed a demo — /demo-insights

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

Makes a freshly mapped board presentable: 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.

3 · Understand

Run insights — /insights

/insights

Insight skills are defined 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

Findings aren't just observations: on the portal, an architect can create an intent from a finding — a work item that flows back to developers through /intents. That's how an analysis becomes a change (see “The loop” below).

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. Skill authoring is covered in Insight Skills.

4 · Build

The build stage is what makes the pipeline two-way: the platform carries your app's build context, and these commands make it real in code.

Pull the compiled skills — /skills

/skills            # sync the compiled bundle into the repo
/skills --status   # read-only: up to date? changed upstream? locally edited?

A skill is composed on the platform from a shared library we curate — you add skills to an app and optionally customize them for that repo — and /skills compiles the resolved result into IDE-native skill files in your repo (for Claude Code: .claude/skills/). These files carry the guidelines and conventions your coding agent follows — they are the primary build context /build builds from.

A compiled skill is more than a single file. Alongside its SKILL.md, a skill can ship:

• reference files — supporting docs under the skill's own folder that the agent loads on demand;
• executable scripts — a scripts/ directory written with the executable bit set, for the deterministic steps a skill defines (a check, a scaffold, a transform). Scripts ship verbatim and read their inputs from argv/env, so nothing inside them is rewritten on the way down;
• a Sources & further reading section, when the skill points at external documentation.

Related skills can also arrive grouped into a named recipe — a curated set that lands together with a short index over its members, so a whole capability shows up in one move rather than as loose parts.

The write is never-clobber: a committed lock manifest (cdx-skills.lock.json) records what the command wrote, so a file you've edited locally — a SKILL.md, a reference, or a script — is detected and left alone, never overwritten. Commit the compiled skills and the lock — the whole team and every agent session then share them.

Note

Skill scripts need a current plugin build. If yours predates script support, /skills still writes the prose and references normally, then reports how many files it held back (N skill file(s) need a newer plugin — run /update). Run /update to get a build that can receive them, then re-run /skills.

Build the app — /build (Cdx Code)

/build           # assemble the build context, plan, implement (after your approval)
/build --plan    # present the plan only — no files touched

/build implements the platform's build context for this app in this repo — including in an empty repo. It assembles a build pack from four sources, by primacy:

1. Compiled skills — the guidelines and conventions (/skills; synced automatically first when stale).
2. Open intents — explicit architect work items.
3. Board design — elements someone designed on the portal that have no source mapping yet ("unbuilt").
4. Aspect contracts — the board's DB-schema and API-surface snapshots, materialized as migrations and endpoint contracts.

It classifies the repo (empty / partial / built), shows a brief with one recommended next step, and — only after you approve the plan — implements the unbuilt work unit by unit, verifying each with the project's own checks. Work an intent covers goes through the /intents claim/resolve machinery, so the architect sees attribution and verification.

/build is incremental and idempotent: the build context keeps evolving on the platform (skills recompiled, intents added, design edited), and re-running builds only the delta. A repo with no unbuilt work is pointed at /intents; a repo with source but no platform build context is routed to Map instead. No dead ends.

Close the loop when it's done: /analyze-archetypes → /analyze → /sync. For a skills-driven build this is what creates the board — the freshly built app becomes a mapped, living board. For a design-led build, the designed elements gain source mappings and stop counting as unbuilt.

Implement architect intents — /intents

/intents              # pull the intent queue and pick one
/intents <intentId>   # claim, implement, verify, resolve a specific intent

An intent is an architect-authored work item: a proposed change to the codebase (or document set), anchored to board elements, that you implement — or reject — from your coding session. The flow is deliberate: claim (single-winner — two developers can't silently duplicate work) → implement from the intent's Instructions and the anchor→file map → verify with the project's own checks → resolve as implemented, rejected, or resolved_other, with a note the architect reads. Stale intents (the board moved since authoring) are flagged and blocked from silent implementation.

An implemented resolution is recorded immediately, and resolutions flow back to the architect's board either way. Where the intent proposed a structural change to the board, it's additionally stamped verified once a later /sync push matches that change — your /sync prints which intents it just proved. An intent that only carries instructions has nothing for the sync to match, so its close stands on your resolution note.

The other half of this queue — authoring intents, creating them from findings, Release, assigning — happens on the portal; see Intents.

5 · Operate

Watch production — /monitor (Cdx Code)

/monitor                          # pull signals from connected monitoring tools
/monitor --input <signals-file>   # or feed an exported/normalized signals file
/monitor --propose-intents        # also file the highest-signal findings as unreleased intents
/monitor setup                    # configure sources + a recurring run

/monitor pulls recent signals from your monitoring tools — error trackers (e.g. Sentry), CloudWatch alarms and log patterns, cloud-cost deltas — and correlates them with your board: a deterministic matcher maps stack frames, resource names, routes, and tags onto board elements, and uncertain matches become teach-once mapping prompts you answer exactly once. The shaped findings land on the portal as a draft insight under the built-in Operational Signals skill — one living instance per board, updated in place on every run, with stable finding ids so the intents you create from them keep their back-references across runs.

From there the loop closes on the portal: an architect reviews the draft, creates intents from the findings that deserve action, and developers pick those up with /intents. Or let the run do the filing: with --propose-intents, the highest-signal findings (a concrete recommendation, high or critical priority) arrive as unreleased intents, back-linked to their findings — they still wait for a person to review and release them. Production problem → board finding → released intent → code fix → the next /sync puts the fix on the board.

/monitor setup scaffolds the monitoring config, prints the MCP connect one-liners for your vendors, and — where the host supports it — creates the recurring run for you (a scheduled task on desktop, a routine in the cloud). For unattended runs, credentials come from the CONTEXTDX_* environment variables; secrets never transit the chat.

The loop (insights as intents)

Put together, the stages form the operating rhythm of a maintained system:

1. /monitor (scheduled) correlates production signals with the board and pushes a draft insight — and /insights analyses contribute findings the same way.
2. An architect reviews on the portal and creates intents from the findings that warrant action, each carrying its origin finding.
3. A developer runs /intents (or /build, which routes intent-covered work through it), claims the item, implements, verifies, and resolves.
4. /analyze + /sync push the changed code; where the intent proposed a structural change, the server matches the push against it and stamps it verified.
5. The next /monitor run shows the signal gone — or escalates it if it isn't.

The board is never just a picture: it's the ledger this loop runs through.

All commands

/help prints this list grouped by stage, with the plugin version. Operational commands are shared by both plugins and behave identically; domain-specific ones are marked.

What the plugins write

Everything project-local 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 + boards/stores/<board-slug>.store.json — per-board analysis data and sync state (element hashes) for smart diffing
• skeletons/ + coverage.json — the deterministic file inventories (repo.json repo-wide, <board-slug>.json per drill-down) and the analysis-coverage ledger (Cdx Code)
• intents/ — the pulled intent queue; insights/ — deterministic context packs for insight runs
• inspections/ — /inspect sessions: clean screenshots plus the picked/annotated metadata
• aspects/ — adopted aspect snapshots; build/ — the /build build pack + pulled aspect contracts
• monitoring/ — /monitor config, signals, and the teach-once mapping file
• caches and an archetype lock file used by the two-phase workflow

Two things are meant to be committed, both written by /skills: the compiled skill files (e.g. .claude/skills/) and their cdx-skills.lock.json — that's how the whole team and every agent session share the platform's operating knowledge.

A single SessionStart hook scaffolds config.json on first run and appends .contextdx/ to your .gitignore. There is no background auto-sync — analysis, sync, and monitoring happen only when you (or a schedule you created) 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). Files in other languages can still be counted toward analysis coverage via coverage.extensions.

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