pi-codebuddy-sdk

Pi extension that registers CodeBuddy as a model provider. You keep using Pi for the TUI, tools, skills, and extensions; CodeBuddy Agent SDK runs inference locally via the codebuddy CLI. No HTTP proxy and no changes to how you work in Pi beyond picking a model.

What it does

• Exposes CodeBuddy models in Pi (codebuddy/... in /model)
• Bridges Pi tools to the SDK (Pi still executes tools; CodeBuddy only plans and calls them)
• Forwards Pi's system prompt and skills so the model acts as Pi—not as standalone CodeBuddy Code
• Supports session resume, compaction, streaming, thinking levels, and images
• Optional AskCodebuddy tool to delegate a focused sub-task to another CodeBuddy call

Install

pi install npm:pi-codebuddy-sdk

Restart pi if it was already running.

Requirements

• codebuddy on your PATH — the extension spawns the same CLI you use standalone. If which codebuddy fails, either add it to PATH or set pathToCodebuddyCode in codebuddy-sdk.json (see Configuration). That option selects the CLI entry point only; the JavaScript runtime used to run it comes from the host, and a Bun-compiled host without a bun on PATH needs provider.executable (see below).
• CodeBuddy auth already working — if codebuddy works in your terminal, you do not need extra setup for this extension.

Quick start (already using CodeBuddy)

No codebuddy-sdk.json and no plugin-specific env vars are required.

1. pi install npm:pi-codebuddy-sdk
2. Restart pi
3. /model → pick codebuddy/...

Optional: set defaultProvider / defaultModel in ~/.pi/agent/settings.json so you skip /model each time.

The first query after startup may take a few seconds while models are discovered from the SDK.

Auth

The extension does not store credentials. The CodeBuddy CLI reads them from your machine. Use one of the following:

1. CLI login (recommended)

codebuddy login

Complete login in the browser. Credentials stay on your machine; Pi reuses them automatically.

2. API key

export CODEBUDDY_API_KEY="your-api-key"

Obtain the key from your CodeBuddy account. Do not commit it or store it in repo files.

3. Managed network environment

export CODEBUDDY_INTERNET_ENVIRONMENT=<environment>
codebuddy login

Set <environment> to the value your CodeBuddy deployment uses. Ask your CodeBuddy administrator if the value is not documented in your deployment's own README, and add CODEBUDDY_API_KEY as well if your environment requires it.

Usage

pi
/model

Pick any entry prefixed with codebuddy/ (for example codebuddy/deepseek-v4.1-flash).

Tools, skills, extensions, /compact, and steer behave the same as with other Pi providers.

Configuration

Optional. Defaults work for most users.

File: ~/.pi/agent/codebuddy-sdk.json or .pi/codebuddy-sdk.json in a project.

{
  "askCodebuddy": {
    "enabled": true,
    "allowFullMode": true
  },
  "provider": {
    "appendSystemPrompt": true,
    "strictMcpConfig": true,
    "pathToCodebuddyCode": "/path/to/codebuddy"
  }
}

modelOverrides lets you fine-tune individual models; the longest matching key wins and beats the global contextWindow / maxTokens:

{
  "provider": {
    "modelOverrides": {
      "gpt-5": { "contextWindow": 1048576, "maxTokens": 64000, "images": false },
      "claude": { "reasoning": true }
    }
  }
}

Supported per-model keys: contextWindow, maxTokens, reasoning, images, thinkingLevelMap.

thinkingLevelMap maps a pi thinking level to the effort string sent to the CodeBuddy CLI. pi only offers xhigh and max when a model declares them here (pi-ai getSupportedThinkingLevels), so a model that supports max upstream stays unreachable until the map names it:

{
  "provider": {
    "modelOverrides": {
      "deepseek-v4.1-flash": { "thinkingLevelMap": { "max": "max" } },
      "space-bunny": { "thinkingLevelMap": { "xhigh": "xhigh", "max": "max" } }
    }
  }
}

Declare only the habits the model actually serves — an effort the backend rejects fails the turn.

Set provider.isolatedEnv to keep Pi turns away from the CodeBuddy IDE's rules, projects, and memory. The extension sends both the CLI subprocess and its own session files to one config dir:

{
  "provider": {
    "isolatedEnv": true,
    "codebuddyConfigDir": "/path/to/private-codebuddy-config"
  }
}

The first run against a new dir needs the CodeBuddy CLI login for that dir.

Window values the backend reports for a model are remembered per model id in ~/.pi/agent/codebuddy-sdk-learned-windows.json, so the next start registers the last served values instead of the name estimate. Precedence: modelOverrides > learned > served metadata > estimate. Delete that file to start from estimates again (ids the backend no longer serves are dropped automatically).

Privacy

• The extension does not send conversation data to this repository or any third-party telemetry endpoint.
• Credentials are handled entirely by the CodeBuddy CLI on your machine.
• Optional debug mode (CODEBUDDY_SDK_DEBUG=1) writes local logs under ~/.pi/agent/; paths are redacted, prompts and tool payloads are not logged. Delete logs when finished.
• CodeBuddy loads project instructions, rules, and project memory independently of --setting-sources; those files can add context that is not part of the Pi session. Set provider.isolatedEnv to use a private config dir with memory disabled.

Troubleshooting

export CODEBUDDY_SDK_DEBUG=1

Default log: ~/.pi/agent/codebuddy-sdk.log. See CONTRIBUTING.md for maintainer details.

After pi -r, the previously selected codebuddy model is gone from /model? The last-known-good model list is cached to ~/.pi/agent/codebuddy-sdk-models.json on every successful discovery, so a new pi process can re-register it synchronously at module load — even when SDK discovery is still in flight (new process, gate busy, or stale auth). If the model is still missing, share the debug log (CODEBUDDY_SDK_DEBUG=1) and the cache file.

Development

Maintainers: CONTRIBUTING.md.

License

MIT

Inspiration

Early MCP bridge patterns were inspired by pi-claude-bridge. This package is a separate codebase on @tencent-ai/agent-sdk.