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
Development has moved to OpenSec’s canonical repository. Use the unscoped opensec-pi-commandcode package for current routing fixes and model support. This repository and @kushalkhemka/pi-commandcode-provider contain the older release; the technical details below describe that older version.
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.
- 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
command-code@1.47.0 - 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
pi install npm:opensec-pi-commandcodeRestart 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- Pi
0.84.4or newer (tested with0.84.4and0.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.
| 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.
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.
| 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 |
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:
- A valid cached catalog is registered immediately.
- A live refresh runs in the background.
- A successful response atomically replaces the cache.
- A failed refresh leaves the last valid catalog active.
- First-time offline startup remains usable, but CommandCode models appear only after connectivity returns and
/commandcode-refreshsucceeds.
Catalog files are written with mode 0600. Overlapping refresh requests are coalesced.
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 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
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.
| 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.
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.
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, and one automatic re-lease attempt handles quota/auth failures before surfacing an 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.
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=1Legacy 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.
/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.
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.
Your account likely does not include Provider API access. Upgrade to a supported plan or knowingly opt into Legacy Go mode.
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.
git clone https://github.com/Kushalkhemka/pi-commandcode-provider.git
cd pi-commandcode-provider
npm ci
npm test
npm run format:checkUseful 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-catalogTest the checkout inside an isolated Pi environment:
npm run pi:isolatedOr use your existing Pi credentials while loading only this checkout:
npm run pi:authenticatedSee CONTRIBUTING.md for testing expectations and RELEASE.md for the package release checklist.
pi update --extensions
pi remove npm:@kushalkhemka/pi-commandcode-providerThis 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.
MIT © Pat Woz and contributors.
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 10 events or after two seconds. 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. Permanent rejections are dropped with a count-only warning. 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.
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.
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.
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.