Install the Pi extension

The native @cardinalhq/pi-plugin is a Pi extension that provides Cardinal tool discovery and execution without a separate MCP extension, and emits session, model-usage, and tool telemetry to the Agent Outcomes dashboard.

Version 0.2.0 supports @earendil-works/pi-coding-agent (tested with 0.85.1). The older @mariozechner/pi-coding-agent distribution has not been verified with this release.

Requirements

• @earendil-works/pi-coding-agent (tested with 0.85.1).
• Node.js 22.19+.
• Python 3.9+ on your PATH.
• macOS or Linux.
• A Cardinal account on app.cardinalhq.io, or a self-hosted Cardinal UI your operator has prepared (see Connect AI clients).

1. Install and register

Install the GitHub release and its dependencies, then register the installed directory with Pi:

npm install --prefix "$HOME/.local/share/cardinal" \
  https://github.com/cardinalhq/cardinal-agent-plugins/releases/download/pi-v0.2.0/cardinalhq-pi-plugin-0.2.0.tgz
pi install "$HOME/.local/share/cardinal/node_modules/@cardinalhq/pi-plugin"

2. Connect

"$HOME/.local/share/cardinal/node_modules/.bin/cardinal-pi" connect

Open the printed URL, sign in, select your organization, and approve the connection. Then restart Pi.

For self-hosted Cardinal UI, append --host:

"$HOME/.local/share/cardinal/node_modules/.bin/cardinal-pi" connect --host https://ui.example.internal

The default is https://app.cardinalhq.io. Pass --telemetry-only to omit the Cardinal tools.

3. Verify

"$HOME/.local/share/cardinal/node_modules/.bin/cardinal-pi" status

Status probes the telemetry and MCP endpoints. A fresh Pi session exposes cardinal_list_tools to discover your organization’s tools and cardinal_call_tool to execute them — no separate MCP extension is needed.

Evidence capture

From version 0.3.0, the result of every tool call (built-in and plugin tools, failed calls included) is kept locally as storyboard evidence, in ~/.cardinal/evidence/ on your machine, with credentials scrubbed, and deleted after 14 days. Cardinal’s own tools are skipped: their results are already witnessed. A call that touches something sensitive, such as a .env file, a private key or a secret-printing command, is withheld: only a stub saying why is kept. The plugin never uploads the spool; a result leaves your machine only when you cite it in an Investigation Storyboard and cardinal-pi evidence promotes it. To opt out, set CARDINAL_EVIDENCE_CAPTURE=0 in the environment Pi starts with, or create the file ~/.cardinal/evidence/disabled.

Disconnect

"$HOME/.local/share/cardinal/node_modules/.bin/cardinal-pi" disconnect

Restart Pi after changing the connection. Disconnect revokes the MCP key and removes the local connection; follow the printed Cardinal API-key settings link to revoke the ingest key as well.

Pull requests and decisions

Session branch state includes the branch’s pull request when gh is installed and signed in and a PR exists.

Decision capture is off by default:

"$HOME/.local/share/cardinal/node_modules/.bin/cardinal-pi" decision on

While it’s on, the extension adds recording instructions plus the session’s decisions so far to each turn’s system prompt, and the agent records choices with the cardinal_record_decision tool. Each decision is sent tagged with the session, repo, branch, and PR. decision off turns it off and decision status shows the current state. While capture is on, each prompt can wait up to 1.5 seconds for the decision list.

Release scope

The v0.2.0 package connects an agent to Cardinal. It does not include the cardinal-install-site skill; use the Data Lake installation guide to set up a new site. Spend enforcement, subscription-plan reporting, and aggregate subagent costs are not included in this release. Session analytics also requires a backend that accepts the pi runtime; successful connection alone does not verify dashboard ingestion. Operators can follow the backend rollout requirements .

See the extension README  for custom state directories and telemetry details.