Install the OpenCode plugin

The native @cardinalhq/opencode-plugin connects OpenCode to Cardinal tools and emits session, model-usage, and tool telemetry to the Agent Outcomes dashboard.

Version 0.2.0 supports the OpenCode 1.x server-plugin API (tested with 1.18.30); OpenCode V2 is not supported. You need Node.js 20+, Python 3.9+ on your PATH, and macOS or Linux.

Requirements

• OpenCode 1.x (tested with 1.18.30). V2 is not supported.
• Node.js 20+.
• 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 the release package

Install the published GitHub release into a stable local directory:

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

Add the following entry to the plugin array in ~/.config/opencode/opencode.json. Create the file if it does not exist; otherwise keep your existing settings and plugin entries. OpenCode expands {env:HOME} to your home directory.

{
  "plugin": [
    "file://{env:HOME}/.local/share/cardinal/node_modules/@cardinalhq/opencode-plugin/index.js"
  ]
}

2. Connect

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

Open the printed URL, sign in, select your organization, and approve the connection. Then restart OpenCode. The plugin registers the cardinal MCP server using the saved connection; an existing mcp.cardinal configuration is preserved.

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

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

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

3. Verify

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

Status probes the telemetry and MCP endpoints. In a fresh OpenCode session, verify that the cardinal MCP server and its tools are available.

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-opencode evidence promotes it. To opt out, set CARDINAL_EVIDENCE_CAPTURE=0 in the environment OpenCode starts with, or create the file ~/.cardinal/evidence/disabled.

Disconnect

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

Restart OpenCode 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-opencode" decision on

While it’s on, the plugin gives chat turns recording instructions plus the session’s decisions so far, 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. The OpenCode hooks this uses are marked experimental in OpenCode 1.x.

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 opencode runtime; successful connection alone does not verify dashboard ingestion. Operators can follow the backend rollout requirements .

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