Skip to main content
Pi is the Pi Agent Harness project. Its @earendil-works/pi-coding-agent package provides an interactive coding agent CLI with file, shell, edit, write, session, print, JSON, RPC, and SDK workflows. Pi can load custom providers from ~/.pi/agent/models.json, so you can add CometAPI as OpenAI-compatible provider entries without changing Pi source code. Official references:
Model availability changes over time. Replace your-model-id with an available model ID from the CometAPI Models page.

​
Prerequisites

  • Node.js >=22.19.0
  • npm
  • A CometAPI account with an active API key from the dashboard
  • Pi installed from the official npm package

​
Understand runtime permissions

Pi runs with the permissions of the user and process that launches it. Start Pi in the project directory you want it to work on, keep a rollback path such as git, and use a container or sandbox if you need stronger filesystem, process, network, or credential boundaries.

​
Configure the provider

1

Install Pi

Install Pi globally with npm:
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
Confirm that the CLI is available:
pi --version
2

Set your CometAPI API key

Store your CometAPI API key in the COMETAPI_KEY environment variable:
read -rsp "CometAPI API key: " COMETAPI_KEY
printf '\n'
export COMETAPI_KEY
Add the export command to your shell profile if you want it to persist across terminal sessions. Do not commit API keys to version control.
3

Add CometAPI providers to models.json

Create ~/.pi/agent/models.json if it does not exist. If the file already contains providers, merge the cometapi-responses and cometapi-chat entries into the existing providers object:
{
  "providers": {
    "cometapi-responses": {
      "name": "CometAPI Responses",
      "baseUrl": "https://api.cometapi.com/v1",
      "api": "openai-responses",
      "apiKey": "$COMETAPI_KEY",
      "models": [
        {
          "id": "your-model-id",
          "name": "CometAPI Responses model"
        }
      ]
    },
    "cometapi-chat": {
      "name": "CometAPI Chat Completions",
      "baseUrl": "https://api.cometapi.com/v1",
      "api": "openai-completions",
      "apiKey": "$COMETAPI_KEY",
      "models": [
        {
          "id": "your-model-id",
          "name": "CometAPI Chat model"
        }
      ]
    }
  }
}
Use cometapi-responses for models or workflows that require the OpenAI Responses API. Use cometapi-chat for OpenAI Chat Completions-compatible models. Pi resolves $COMETAPI_KEY at request time. Keep the API key in your environment or in your own secrets workflow.
4

Verify both providers

List the models that Pi can see for the Responses provider:
pi --list-models cometapi-responses
Run a short one-shot prompt with the Responses provider:
pi --provider cometapi-responses --model your-model-id -p "Reply with one short sentence confirming the Responses connection."
List the models that Pi can see for the Chat Completions provider:
pi --list-models cometapi-chat
Run a short one-shot prompt with the Chat Completions provider:
pi --provider cometapi-chat --model your-model-id -p "Reply with one short sentence confirming the Chat Completions connection."
For interactive use, start Pi in your project and select the CometAPI provider and model with /model. If you edit models.json during an interactive session, open /model again so Pi reloads the custom model entries.

​
Troubleshooting

Confirm that ~/.pi/agent/models.json is valid JSON and that each provider entry is inside the top-level providers object. Run pi --list-models cometapi-responses or pi --list-models cometapi-chat after saving the file.
Confirm that COMETAPI_KEY is set in the same shell session that launches Pi. If you use a shell profile, open a new terminal or source the profile before running Pi.
Use https://api.cometapi.com/v1 as the baseUrl in models.json. Do not point Pi at the dashboard URL or omit the /v1 suffix for OpenAI-compatible routes.
Check your Node.js version with node --version. The Pi package requires Node.js >=22.19.0.
Use the provider entry whose api field matches the route your model supports. openai-responses uses the Responses API, while openai-completions uses Chat Completions.
Pi runs with the permissions of the user and process that launched it. Run Pi inside a container or sandbox when you need stronger boundaries around files, processes, network access, or credentials.