CommandCode for Pi

Use CommandCode models in Pi through the documented Provider API—with native streaming, tools, reasoning, vision, prompt caching, usage accounting, and resilient model discovery.

Install · Compatibility · Configuration · Troubleshooting · Contributing

[!IMPORTANT] This is an unofficial, community-maintained integration. It is not affiliated with or endorsed by CommandCode. You need your own account and a plan with Provider API access.

Why this package

• Native Pi streaming through Pi's maintained OpenAI and Anthropic adapters
• Full agent loops with incremental tool arguments, reasoning, images, usage, aborts, and retries
• Stable prompt-cache routing using Pi session IDs on OpenAI-compatible requests
• Live model discovery with cache-first startup and background refresh
• Current capabilities synchronized from [email protected]
• Explicit pricing coverage for every model in the current live Provider API catalog
• Zero-data-retention header support through CMD_ZDR=1
• No runtime dependency bundle—the extension uses Pi's own core packages

Install

pi install npm:opensec-pi-commandcode

Restart Pi or run /reload, then authenticate:

/login

Choose Use a subscription → Command Code, finish browser login or paste an API key, then select a model:

/model

You can also list models non-interactively:

pi --list-models commandcode

Requirements

• Pi 0.84.4 or newer (tested with 0.84.4 and 0.85.0)
• Node.js 20 or newer when developing or running scripts directly
• A CommandCode plan with Provider API access

The documented Provider API is unavailable on the Go plan. See Legacy Go mode before opting into the unsupported fallback.

Compatibility

| Capability | Pi behavior | Transport | | ----------------- | ---------------------------------------------------- | -------------------------------------------- | | Text streaming | Incremental deltas | OpenAI Chat Completions / Anthropic Messages | | Tool calls | Incremental JSON arguments and complete tool results | Native Pi adapters | | Reasoning | Model-specific supported effort levels | Synced CommandCode CLI catalog | | Images | Advertised only for verified vision models | Native multimodal schemas | | Prompt caching | Stable prompt_cache_key per Pi session | OpenAI-compatible models | | Anthropic caching | Pi's short-lived cache annotations | Anthropic-compatible models | | Usage | Input, output, cache-read, and cache-write tokens | Final streamed usage events | | Cost display | Explicit per-model pricing with long-context tiers | Reviewed static overlay | | ZDR | Sends x-cmd-zdr: 1 when enabled | Documented CommandCode header | | Offline startup | Last valid model catalog loads immediately | Local cache + background refresh | | Context overflow | Normalized for Pi auto-compaction | Both documented Provider API routes |

The primary path uses only these documented endpoints:

GET  /provider/v1/models
POST /provider/v1/chat/completions
POST /provider/v1/messages

CommandCode's first-party CLI includes its own prompts, tools, and harness optimizations. This package targets wire-protocol and Pi runtime compatibility; it does not claim to reproduce the proprietary first-party harness.

Authentication

The recommended flow is Pi's /login command. The provider also accepts:

export COMMAND_CODE_API_KEY="user_..."

Existing credentials can be read from:

• ~/.commandcode/auth.json
• ~/.pi/agent/auth.json

Supported shapes include:

{ "apiKey": "user_..." }

{
  "command-code": {
    "type": "api",
    "key": "user_..."
  }
}

Credentials are never written to this repository or included in package output.

Provider commands

| Command | Purpose | | ---------------------- | ------------------------------------------------------------------------------------------- | | /commandcode-status | Show transport, catalog source, model count, cache path, refresh state, and redacted errors | | /commandcode-refresh | Refresh and re-register the live model catalog without restarting Pi | | /commandcode-quota | Show available credits, plan information, and rolling usage windows |

Model discovery and caching

The provider fetches models from https://api.commandcode.ai/provider/v1/models.

The last valid catalog is stored at:

~/.pi/agent/commandcode-models.json

Startup behavior is deliberately resilient:

1. A valid cached catalog is registered immediately.
2. A live refresh runs in the background.
3. A successful response atomically replaces the cache.
4. A failed refresh leaves the last valid catalog active.
5. First-time offline startup remains usable, but CommandCode models appear only after connectivity returns and /commandcode-refresh succeeds.

Catalog files are written with mode 0600. Overlapping refresh requests are coalesced.

Prompt caching

For OpenAI-compatible models, the extension supplies a stable, maximum-64-character prompt_cache_key derived from Pi's session ID. This helps compatible upstream routing keep related turns on the same cache path. Setting Pi's cache retention to none disables the field.

For Anthropic-compatible models, Pi applies its native short-lived cache annotations. The extension does not claim unsupported long-retention behavior.

Reasoning, tools, and images

Reasoning and vision capabilities are generated from the published CommandCode CLI catalog. Each model exposes only the thinking levels accepted by its current metadata.

Vision-capable models accept image blocks from direct user messages and tool results. Unknown or explicitly text-only models remain text-only, preventing lossy requests.

Provider API streaming is delegated to Pi's native adapters. This preserves:

• interleaved reasoning and text
• fragmented tool-call arguments
• multiple concurrent tool calls
• final usage-only chunks
• cancellation and bounded retry behavior
• correct cached-token accounting

Pricing

The Provider API catalog does not currently include rates. This extension therefore maintains an explicit pricing overlay sourced from the CommandCode pricing page.

The current live catalog is checked daily. CI fails when a model is added without both:

• an explicitly reviewed price entry, including free models
• a synchronized catalog fixture

Displayed costs are estimates. CommandCode's usage page remains authoritative for actual billing, promotions, and time-dependent rates.

Configuration

| Variable | Default | Description | | -------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------------------- | | COMMAND_CODE_API_KEY | — | Preferred API-key environment variable | | CMD_ZDR=1 | disabled | Send CommandCode's documented zero-data-retention header | | COMMANDCODE_API_BASE | Provider API URL | Override the Provider API base for local tests or compatible gateways | | COMMANDCODE_MODELS_URL | /provider/v1/models | Override model discovery | | COMMANDCODE_MODELS_CACHE | Pi agent directory | Override the catalog cache path | | COMMANDCODE_MODELS_TIMEOUT_MS | 10000 | Bound model discovery and refresh requests | | COMMANDCODE_ENABLE_LEGACY_GO=1 | disabled | Explicitly enable the undocumented Go-plan fallback | | COMMANDCODE_QUOTA_BOARD_URL | disabled | Send final Pi usage to a running local Quota Board | | COMMANDCODE_QUOTA_BOARD_TOKEN | — | Bearer token for a non-loopback Quota Board | | OPENSEC_ROUTER_URL | https://cc.opensec.in for member tokens; otherwise disabled | Lease a sticky CommandCode key from an OpenSec control plane | | OPENSEC_ROUTER_TOKEN | provider credential | OpenSec access token; use this instead of a CommandCode key in Pi |

Legacy aliases COMMANDCODE_API_KEY, COMMANDCODE_ZDR, and existing auth-file shapes remain accepted for migration compatibility.

CommandCode Quota Board

The repository includes a separate multi-account quota dashboard with pure-black and light themes, global and per-key statistics, rolling quota windows, associated account emails, and encrypted local key storage.

To populate its model and cache charts automatically from Pi's final streamed usage events:

export COMMANDCODE_QUOTA_BOARD_URL="http://127.0.0.1:8787"

The provider sends a one-way, best-effort usage event after each completed or failed request. It sends a short hash fingerprint—not the API key—so the board can match the event to an account already connected there. Dashboard availability never delays or breaks a Pi response.

Sticky multi-account routing

An OpenSec quota-board deployment with router support can act as a lightweight control plane for a trusted Pi installation. It leases one real CommandCode key to each Pi session, while generation requests and streamed output continue to travel directly between Pi and CommandCode:

export OPENSEC_ROUTER_URL="https://cc.opensec.in"
export OPENSEC_ROUTER_TOKEN="<your OpenSec access token>"

Configure the same token as the Pi provider credential when environment injection is not available. The control plane keeps an established session on its assigned account until the client reports an authentication or explicit quota failure. When rotation is required, it selects the eligible account with the highest safe remaining quota; equal safe headroom is resolved by the highest aggregate remaining capacity. The plugin keeps leased upstream keys only in process memory. Renewal starts on use when the returned lease expiry is within one minute: Pi immediately keeps using the current upstream key while a small control-plane request renews it in the background, so an active stream is never interrupted. Final usage is reported asynchronously. Explicit quota failures carry only the failed lease, quota window, and provider reset time back to the control plane; the account is excluded globally until reset without an additional CommandCode quota check. A request walks up to 64 distinct leased accounts before surfacing the last provider error.

Because the trusted plugin receives the selected upstream key, this mode avoids proxy latency but cannot conceal CommandCode credentials from the machine running Pi. Use TLS and protect OPENSEC_ROUTER_TOKEN as a personal access credential.

Legacy Go mode

CommandCode's documentation excludes Go from Provider API access. This extension therefore keeps the undocumented /alpha/generate fallback disabled by default.

If you understand that the endpoint is unsupported and may change without notice, enable it explicitly:

export COMMANDCODE_ENABLE_LEGACY_GO=1

Legacy mode includes streaming reasoning, incremental tool arguments, usage accounting, bounded retries, and pause_turn continuation. It is not covered by the public Provider API compatibility guarantee.

Troubleshooting

No CommandCode models appear

/commandcode-status
/commandcode-refresh

Check the reported endpoint, cache state, and redacted warning. On first use, live model discovery must succeed once before offline startup can use a cache.

401 or missing credentials

Run /login again, or verify that COMMAND_CODE_API_KEY is available to the Pi process. Avoid placing tokens directly in shell history, repository files, or issue reports.

403 upgrade_required

Your account likely does not include Provider API access. Upgrade to a supported plan or knowingly opt into Legacy Go mode.

Long request appears idle

Pi's provider timeout and retry settings apply. A value of httpIdleTimeoutMs: 0 can be useful for models that pause for long reasoning periods, but consider the risk of genuinely stuck connections.

Development

git clone https://github.com/opensec-git/pi-commandcode-provider.git
cd pi-commandcode-provider
npm ci
npm test
npm run format:check

Useful focused checks:

npm run test:models
npm run test:stream
npm run test:transport
npm run test:pi-local
npm run check:live-catalog
npm run check:commandcode-catalog

Test the checkout inside an isolated Pi environment:

npm run pi:isolated

Or use your existing Pi credentials while loading only this checkout:

npm run pi:authenticated

See CONTRIBUTING.md for testing expectations and RELEASE.md for the package release checklist.

Update or remove

pi update --extensions
pi remove npm:opensec-pi-commandcode

Acknowledgements

This project is a maintained fork of patlux/pi-commandcode-provider. Thanks to Pat Woz and every upstream contributor who built and tested the original integration.

License

MIT © Pat Woz and contributors.

OpenSec team access and telemetry

Each member uses their own OPENSEC_ROUTER_TOKEN issued from the OpenSec Team & access page. The upstream CommandCode pool stays shared. No upstream key or quota share is reserved for a member. Sessions are cached separately for each router token.

Routed usage is attributed to the request's lease, including after rotation. Reports use stable event IDs, batched at up to 25 events or after a randomized 10–15 second interval. Only one upload runs per process; buffered and in-flight payloads share a 256 KiB cap. Transient failures retry with backoff and Retry-After, for up to five attempts / five minutes. On servers supporting partial acknowledgements, invalid reports are rejected individually while valid reports commit; whole-request authentication failures still reject the batch. Background model-catalog and telemetry warnings are silent by default. Run /commandcode-status to inspect diagnostics and telemetry counters, or start Pi with COMMANDCODE_DEBUG=1 to enable background warnings. Explicit command results and request failures remain visible. Diagnostics exclude credentials and report bodies. No prompts or response text are sent. Generic quota-board reporting is suppressed while router mode is active to avoid duplicate reporting. Normal shutdown attempts a bounded flush; an abrupt exit may lose buffered events. This is best-effort attribution, not verified billing or hard spending enforcement.

Deploy the team-capable server before this plugin: batching requires POST /api/router/usage. Existing older plugins continue to work with the server's single-event lease endpoint, but those older reports cannot be deduplicated across retries without event IDs.

OpenSec login without environment variables

In the updated plugin, run /login, select Command Code, and paste your os_member_... token at the login prompt. Pi saves it in its local credential store. The plugin recognizes this token and leases from https://cc.opensec.in automatically; neither OPENSEC_ROUTER_URL nor OPENSEC_ROUTER_TOKEN is required. The first model request checks the token with the router; login checks its format only. Expired or revoked tokens are rejected by the router.

Ask the workspace owner to create your token under your member in Team & access → OpenSec API keys. The /commandcode-quota command points OpenSec members to the dashboard for their usage. Ordinary CommandCode keys continue to use direct access. For another OpenSec deployment or an old shared token, keep the explicit router URL configuration. Existing environment credentials take precedence over saved credentials; remove an old OPENSEC_ROUTER_TOKEN before switching members.

OpenSec lease affinity

The lease manager reuses one upstream key per authenticated Pi session and keeps Pi's stable prompt-cache key. Temporary 429 throttling and 5xx errors return to the normal retry/backoff policy without requesting a different account. Invalid credentials, payment failures and explicit quota exhaustion can still rotate. A rotation includes the failed account and lease ID, so concurrent or delayed failures reuse the replacement. Slow background renewal responses cannot restore an older lease, and subsequent retries use the current key even if the transport retained earlier authorization headers.

When CommandCode returns an explicit rolling-window reset time, the same rotation reports that timestamp to OpenSec. The server validates it against the caller's lease and temporarily removes the account from all new allocations. The client keeps a per-request exclusion set, so consecutive exhausted accounts are never retried during the same generation.

The router preserves assignments across renewal and restart. Cache lifetime and actual cache hits remain controlled by CommandCode and its upstream providers.

Router overrides require HTTPS (HTTP is accepted only for literal loopback addresses during local development), without URL credentials, queries or fragments. Lease and usage uploads reject redirects. Router error bodies are not displayed in Pi. A custom router is a trusted credential recipient selected through local configuration; do not configure an endpoint you do not control.