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.

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 on app.cardinalhq.io, or 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

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.

Privacy

By default the plugin captures bash command lines and file paths so Cardinal can tell which repo and service a session worked on. The contents of your prompts and tool inputs/outputs are never captured. If your org’s policy forbids command lines and paths too, connect with --no-tool-details — sessions still appear, but as repo=unknown.

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.