Install the Claude Code plugin

The cardinal-claude-plugin is what puts your Claude Code sessions on the Agent Outcomes dashboard. One browser-approved consent wires up both halves:

Telemetry — your sessions stream to Cardinal, attributed to engineer, branch, PR, and initiative, with per-turn token and tool usage for the dashboard’s cost and anti-pattern analysis.
MCP tools — a single cardinal MCP server appears in Claude Code, exposing whichever tools your org has integrations for (Cardinal Data Lake, GitHub, Jira, …). Pass --telemetry-only if you want the dashboard side without the tools.

The plugin also delivers session context and spend limits: every session in a git repo receives the initiative branch-naming convention at start, and any spend-limit policies your org has set are enforced in-session — quiet context at notify, a visible message at warn, a stopped turn at block.

The plugin works in two modes:

Installed, not connected: local-only. The cardinal MCP server has no URL yet, so it contacts nothing; /mcp lists it as failed with Missing environment variables: CARDINAL_MCP_URL, which is expected. The plugin captures tool results on your machine and sends nothing. There are no Cardinal tools, no session telemetry, no spend limits, and no session-context hooks. The first session tells you once how to connect.
Connected with /cardinal:connect. The cardinal server uses your org’s URL and an API key the connect flow created. You get the Cardinal tools, Investigation Storyboards with the storyboard skills, local previews and cited evidence uploads, plus the session telemetry, session context and spend limits described on this page.

Writing to Cardinal, storyboards included, needs that API key; there is no OAuth sign-in. On a self-hosted or in-VPC Cardinal UI, run /cardinal:connect --host ….

Reach out to support@cardinalhq.io for support or to ask questions not answered in our documentation.

Coordination on agent intent

Plugin 0.62.0 lets the agent choose when coordination matters, during reasoning, planning, decisions, answering or other work. Supervisor and worker share the same operations:

investigation sync --intent PURPOSE catches up on fresh collaborator information.
investigation request --assignee PRINCIPAL --assignee-session SID --intent PURPOSE --text REQUEST declares a required result for that work.
investigation wait --intent PURPOSE waits until new information or a result needs attention. Reuse the exact purpose to resume after an interruption; --request Q adds an existing prerequisite.

Ordinary tools are not classified or blocked by coordination. There is no fixed list of edits, commits or other supported actions, and no mode setting, policy file or enable command. Normal delivery can notify the agent about new information; explicit synchronization retains its own handling and dependency state.

The assignee responds complete, blocked, abstain or reject. Only the requester accepting the exact complete result, or cancelling with a reason, resolves the dependency. Reading, acknowledgment and timeout never release it. Unrelated purposes remain available. New feedback interrupts a wait for handling.

Waiting uses one bounded CLI invocation with incremental reads and backoff; it is not server push or indefinite host parking. A timeout leaves the intent and required results durable. Use the request commands and the runtime contract for feedback review, exact references, outcomes and resumption.

Deploy backend support for coordination_intents version 1 and request_protocol:2 before upgrading clients. Upgrade participants sharing an Investigation before creating intent-only requests: old clients fail closed on those records. Existing records remain readable; their old action categories do not intercept tools in new clients. Broader fleet/performance acceptance remains separate work.

Requirements

Claude Code with plugin support (any recent stable release).
Python 3.9+ on your PATH (the plugin’s helpers run as Python scripts).
A Cardinal account: sign up at app.cardinalhq.io (without an invitation you get a personal workspace), or use a self-hosted Cardinal UI your operator has prepared (see Connect AI clients).

1. Install


claude plugin marketplace add cardinalhq/cardinal-claude-plugin
claude plugin install cardinal@cardinalhq-claude-plugin

2. Connect

Connecting is what gives Claude Code write access to Cardinal, storyboards included: the consent flow creates an API key for the org you pick and the plugin stores it. You don’t create a key yourself.

From inside Claude Code:


/cardinal:connect

The plugin prints a URL like https://app.cardinalhq.io/connect?code=ABCD-EFGH. Open it in your browser, sign in if you aren’t already, pick the org to connect, and click Approve. The plugin picks up your consent within a few seconds and writes the config.

For self-hosted Cardinal UI, pass your host:


/cardinal:connect --host https://ui.example.internal

With --host set, nothing touches Cardinal Cloud: your Cardinal UI runs the consent flow, mints the keys, and hands the plugin your endpoints — MCP on your Cardinal UI, telemetry to your Cardinal Data Lake intake. The telemetry side requires your operator to have set MAESTRO_INGEST_ENDPOINT on the Cardinal UI deployment (see Environment variables); without it the connect bundle omits telemetry and sessions never reach the dashboard.

Then fully quit Claude Code (Cmd-Q on macOS) and start a new session — the telemetry and MCP settings are read at process start.

3. Verify

From the new session:


/cardinal:status

You’ll see the host, your org, both endpoints, key prefixes, and a reachability probe against each side. Run a session in any git repo and it appears on the Outcomes dashboard within a few minutes.

Variants


/cardinal:connect --telemetry-only      # Outcomes dashboard only; skip the MCP tools
/cardinal:connect --rotate              # Mint fresh keys, overwrite an existing connection
/cardinal:connect --host https://…      # Point at a self-hosted Cardinal UI
/cardinal:connect --no-tool-details     # Privacy opt-out — see below
/cardinal:connect --dry-run             # Walk the consent flow, write nothing

Getting attributed correctly

Sessions are attributed to an initiative by branch name: <type>/<kebab-name>, where the type prefix is one of feat, fix, refactor, infra, chore, research, or spike (for example feat/outcomes-observability → initiative outcomes-observability, type feature). Sessions on main/master/develop/trunk are treated as research/scoping work. The plugin reminds Claude of this convention at the start of every session, so branches it cuts for you classify cleanly.

Pull requests and decisions

Each prompt’s branch state includes the branch’s pull request when the GitHub CLI (gh) is installed and signed in and a PR exists for the branch, so sessions link to their PR directly.

Decision capture is off by default. To turn it on, set CARDINAL_DECISIONS=1 in the env block of ~/.claude/settings.json and start a new session, or run the plugin’s cardinal-decision on. While it’s on, the plugin asks Claude to record each material choice (the question, the option chosen, why, and what it rejected) with cardinal-decision record, and each one is sent to Cardinal tagged with the session, repo, branch, and PR. cardinal-decision off turns it off.

If you use Claude Code’s Bash sandbox, the record command needs to write ~/.claude/cardinal and reach your Cardinal ingest host, so Claude Code asks before running it outside the sandbox. Add both to your sandbox allowlist to skip the prompt.

Automatic Storyboards

Connected sessions automatically get an Investigation. Findings and cited evidence appear in Activity as Claude works. Ask Claude to publish the storyboard: the skill updates its scenes from the investigation, renders and refines previews, then validates and publishes it. There is no recurring end-of-work offer or stop-hook update prompt. A request only to update the visualization keeps the draft private. A storyboard is private to its author until it is shared with your org; publishing its first act shares it. The UI and server do not generate visuals. This workflow does not require owner-input capture. See session-owned visualization.

Storyboard skills

From version 0.32.0, the plugin ships two skills for Investigation Storyboards. Claude uses them on its own when you ask it to write up, explain, or storyboard an investigation, and you can also invoke them directly:

Skill	What it does
`/cardinal:storyboard`	Turns an investigation into a storyboard: picks the minimum sequence of scenes, cites the receipts behind every number, types each claim honestly, then validates, previews, and publishes. It hands you the storyboard’s `view_url`.
`/cardinal:canvas`	Draws each scene’s visual, then renders every scene locally in your Chrome or Chromium and critiques the images before Claude publishes.

Once connected, the plugin also adds this session’s Cardinal session id to Claude’s context at session start, so each storyboard records which session wrote it.

From version 0.36.0, the storyboard skill looks for an existing storyboard to update before it creates one. It runs the plugin’s cardinal-storyboard context command, which prints where you are working (repository, path within it, branch, pull request, commit, a hashed directory id, the plugin version and your Cardinal account email), passes that to storyboard__find, and asks you before it adds an act to a match. See Update an existing storyboard.

From version 0.39.6 (Claude Code 2.1.0 or newer), the plugin also fills in the session id and where you are working when Claude creates or finds a storyboard, so Claude no longer pastes cardinal-storyboard context. It records which files the session edited, tells Claude how a related storyboard relates to your work (about it, or only written from the same checkout) at session start, after a merge and before an edit, and renders the link-preview cover and a mock of the unfurl locally. See Associations and Link previews: headline and cover.

The skills and local previews need the plugin to be connected: before /cardinal:connect there are no storyboard__* tools. Evidence capture runs either way, so results captured before you connect can be cited afterwards. See Use storyboards with Claude.

Authoring needs the Member or Owner role in the org Claude works in.

Evidence from your other tools

From version 0.35.0, a hook keeps the result of every tool call on your machine, under ~/.cardinal/evidence/, so a storyboard can cite it as captured evidence. That includes shell commands, file reads and edits, web fetches and your other MCP servers, but never Cardinal’s own tools, which are already witnessed. Credentials are scrubbed, each result is capped at 256 KiB, and entries are deleted after 14 days. A call that touches something sensitive, such as a .env file, a private key or gh auth token, is withheld: only a stub saying why is kept, and it can’t be cited. Nothing is uploaded until an Investigation checkpoint or Storyboard cites a result: Claude then runs cardinal-evidence promote for exactly those results. Turn capture off with cardinal-evidence off. See Captured evidence.

Local previews

The /cardinal:canvas skill renders previews with a script bundled in the plugin, render_preview.py. The script runs on your machine and needs no extra Python packages. It downloads each scene’s self-contained preview page from the Cardinal the plugin is connected to, checks its size and SHA-256, and opens it in a local headless Chrome or Chromium. That browser runs with its OS sandbox on, networking locked off, and a throwaway profile. The script writes one PNG per scene and reveal step to ~/.claude/cardinal/storyboards/<storyboard id>/r<revision>/ for Claude to read. Your Cardinal key is only ever sent to that Cardinal.

Requirements:

Google Chrome or Chromium 112 or later on macOS or Linux. The script looks for Chrome, Chromium, Chrome Canary, Brave, and Edge in their usual install locations, then in the Playwright and Puppeteer download caches.
To use a specific browser, set CARDINAL_CHROMIUM to its binary path. When it’s set, that is the only browser the script tries.
On Linux, Chromium needs unprivileged user namespaces to start with its sandbox on. Many containers and locked-down images don’t allow them. The script never turns the sandbox off, so previews are skipped there.
Windows is not supported. Claude authors and publishes without previews.

Previews are optional. Publishing never depends on them, because Cardinal’s publish checks are deterministic and don’t look at pixels. The script’s exit code tells Claude what to do:

Exit code	Meaning
`0`	The script ran. Individual scenes may still report errors, which Claude fixes.
`2`	Nothing was rendered because of a connection, authentication, or fetch problem: not connected, a different org, a role without access, a draft edited since the last preview, or a Cardinal too old to serve previews. Claude reports the reason and, for a stale preview, previews again.
`3`	No usable local Chrome or Chromium, Windows, or Chromium could not start with its sandbox on. This is not an error. Claude tells you once that previews were skipped and keeps authoring.

A preview page is fetched by its path on the Cardinal the plugin uses. On a self-hosted Cardinal UI, previews work whether or not your operator has set MAESTRO_BASE_URL; that setting only decides whether the view_url Claude hands you is an absolute link or a path to open on your Cardinal UI host. On Cardinal Cloud, both are already set up.

After upgrading: reconnect with `/mcp`

Claude Code reads the cardinal server’s tool list when a session connects. A session that was open before you upgraded the plugin, or before your Cardinal was upgraded, may not see the newest storyboard__* tools, and may reject tool results that carry a receipt. Run /mcp and reconnect the cardinal server, or start a new session.

Privacy

Until you run /cardinal:connect, the plugin sends no session telemetry at all. Once connected, by default it captures bash command lines and file paths so Cardinal can tell which repo and service a session worked on. Session telemetry carries no prompt contents, tool outputs, or tool inputs beyond those command lines and paths. Optional Investigation owner-input capture is a separate capability, disabled by default and disclosed before the first capture; it is not required for Storyboards and is never sent to the projector. If your org’s policy forbids command lines and paths too, connect with --no-tool-details — sessions still appear, but as repo=unknown.

Tool results are handled separately, as storyboard evidence. Capture works the same way whether or not the plugin is connected:

Results of every other tool call (shell commands, file reads and edits, other MCP servers, …) are kept locally as evidence, in ~/.cardinal/evidence/ on your machine, with credentials scrubbed, and deleted after 14 days. A call that touches something sensitive, such as a .env file, a key or a secret-printing command, keeps no arguments or result, only a stub saying it was withheld. They are uploaded only when you cite them in a storyboard, and then only to that storyboard’s open draft act. To opt out, run cardinal-evidence off (or set CARDINAL_EVIDENCE_CAPTURE=0); cardinal-evidence on turns it back on. See Captured evidence.
Results of Cardinal’s own tools already run on Cardinal. Cardinal keeps a receipt of each read-only call, with credentials redacted, for 14 days, or for as long as a published storyboard cites it. See Evidence and receipts.
Where a storyboard was written. From version 0.36.0, when Claude creates a storyboard, adds an act, or looks for one to update, the plugin sends the context cardinal-storyboard context prints: repository, path within it, branch, pull request, commit, a hashed directory id, the plugin version and your Cardinal account email. It never sends an absolute path. Only members of your org can see it, never readers of a public link. See What each act records.
Looking up storyboards for your work. In plugin versions after 0.36.0, a connected plugin asks Cardinal at session start, and again when the branch or commit changes, for storyboards with the same pull request, branch or directory, sending the repository, the path within it, the branch and the pull request number. Set CARDINAL_STORYBOARD_DISCOVERY=0 to turn it off. See Reviewing and debugging with storyboards.
What the plugin adds on its own (from 0.39.6). A hook adds the session id and the context above to storyboard calls that leave them out; CARDINAL_STORYBOARD_CONTEXT=0 turns that off. The files a session edits are recorded locally as repository-relative paths and sent as part of the context when a storyboard is created, extended or published, and members of your org can see them once the storyboard is shared with the org (publishing its first act shares it). On a private storyboard they stay visible only to its author. CARDINAL_STORYBOARD_CONTEXT=0 stops the hook from adding them. The lookup before an edit asks Cardinal for storyboards about that file, once per directory, and shares the discovery opt-out. On main, discovery sends the numbers of recently merged pull requests and the names of your recent local branches to your Cardinal. See Privacy.
Link-preview cover. After a storyboard is published, a hook uploads the cover image your machine rendered (at most 2 MiB) to that storyboard in your Cardinal. Set CARDINAL_STORYBOARD_HERO=0 to skip it. See The cover image after publish.

Disconnect


/cardinal:disconnect                    # Remove everything the plugin added
/cardinal:disconnect --keep-telemetry   # Keep the dashboard side, remove the MCP tools

Disconnect revokes the keys with Cardinal and removes only the plugin-owned settings; everything else in your Claude Code config is left as it was. After a full disconnect the plugin is local-only again: the cardinal server has no URL, and evidence capture stays on your machine.