A local provider plugin for streaming replies, native tools, and resumable coding sessions.
Quick start · Features · Configuration · Validation · Contributing
Bring ZCode's agent into bb. Choose ZCode in a thread, send a prompt, follow its work, and return to the same conversation later. The plugin runs your installed ZCode CLI and uses its existing provider configuration.
Note
Supports individual Coding Plan sign-in in ZCode Desktop (Z.ai / BigModel) and personal API providers configured in ZCode. Start Plan and Team plans are not supported yet.
| What you get | |
|---|---|
| Live conversations | Stream text and reasoning directly into bb. |
| Native tools | Follow ZCode tool calls and results in the thread. |
| Human decisions | Answer approvals and questions through bb. |
| Session continuity | Stop, release, resume, fork and rewind conversations. |
| Background work | Track native Bash/agent tasks; list, inspect output and cancel. |
| File rollback | Preview and explicitly apply native file checkpoints. |
| Model discovery | Choose from ZCode's models and reasoning options. |
| bb extensions | Enable bb plugin tools and load bb skill files. |
| Custom agents | Configure native subagents and answer their questions in bb. |
| Plan mode | Ask ZCode to inspect the workspace and prepare a plan. |
Each thread runs its own supervised ZCode process. The plugin reads ZCode's existing sign-in and keeps short-lived Coding Plan credentials in memory; there are no API-key settings to fill in or credentials to paste into bb.
You'll need bb 0.46.1, Node.js 24+, and a local ZCode installation with individual Coding Plan connected in ZCode Desktop or a personal API provider configured. Start bb before installing the plugin.
Open Settings → Plugin marketplaces, paste this into Marketplace source, and click Add:
https://raw.githubusercontent.com/dpolishuk/bb-zcode/main/marketplace.json
In bb's plugin store, search for ZCode, open the entry from ZCode for bb, and click Install. bb downloads, builds, and manages the plugin for you. Adding the marketplace alone does not install a plugin.
You can also paste this Git source into the same field:
git:https://github.com/dpolishuk/bb-zcode.git@main
The plain https://github.com/dpolishuk/bb-zcode repository page is not a
marketplace manifest; bb 0.46.1 requires the raw JSON URL or git: source above.
With the bb CLI on PATH, the equivalent is:
bb marketplace add git:https://github.com/dpolishuk/bb-zcode.git@main
bb plugin install zcode@bb-zcodeThe catalog and plugin track main. Use bb's native update controls or
bb plugin update zcode to install later compatible changes. See
marketplace details for refresh and verification.
For local development:
git clone https://github.com/dpolishuk/bb-zcode.git
cd bb-zcode
npm ci --ignore-scripts
npm run check
node scripts/bb.mjs plugin install . --yesOpen a new bb thread, select ZCode, choose a model, and send a prompt.
On the machine running bb, sign in to ZCode Desktop and open Coding Plan once, then update the plugin and open a new bb thread:
bb plugin update zcode --yes
bb provider models zcode --jsonThe list should contain actual model names and their supported effort choices.
For example, the verified ZCode catalog exposes GLM-5.3 / GLM-5.3-Flash with
low, high, and max. Choices follow your installed ZCode catalog.
The installer helper uses bb's installed macOS app CLI, or bb on PATH on
other systems. The provider finds zcode on PATH, then tries the CLI bundled
in /Applications/ZCode.app.
Using a custom ZCode or Node installation?
Set the paths on the machine running your bb threads:
node scripts/bb.mjs plugin config zcode set executable /absolute/path/to/zcode.cjs
node scripts/bb.mjs plugin config zcode set nodeExecutable /absolute/path/to/node
node scripts/bb.mjs provider models zcodeSee configuration for launch arguments, environment overrides, permission modes, and troubleshooting.
| Component | Tested with |
|---|---|
| bb | 0.46.1 |
| bb plugin SDK | 0.6.49 |
| ZCode CLI | 0.16.9 and 0.17.0 · native protocol v1 |
| Platform | macOS |
| CLI runtime | Node.js 24 and 26.5.0 |
Automated tests cover the bridge contract, streaming, approvals, questions, cancellation, resume, account authentication, and transport failures. An end-to-end check also passed through bb → this plugin → the real ZCode CLI, using a deterministic local model fixture.
See the validation record for what was tested and what remains unverified. Personal provider authentication and production model connectivity have not been tested. Linux and Windows launch support is implemented but has not received the same live verification.
- Follow-ups queue until the running turn finishes. Images, files, token/context reporting, and native manual compaction are supported.
- MCP servers can be configured at session startup. Official MCP authentication supports individual Coding Plan on the default ZCode endpoint. Native memory and enhanced search are optional settings; see configuration.
- The optional bb tool bridge retains plugin presentations and text/image results. bb skill catalogs point to original files; they are not added to ZCode’s native Skill catalog. Custom subagents and nested tool attribution are supported; Bash rows retain output.
- Native forks and conversation rewind use stable checkpoints. Background Bash/agent cards and task commands survive foreground settlement. File rollback has separate preview/apply commands; see configuration.
- File edits and reads, searches, web fetches, plan steps and delegations render as rich bb rows; full unified-diff views, cost billing and a full subagent tree remain unsupported.
- The provider usage panel reports account status and the Coding Plan label
without invented numbers, and
/zcode-checkruns ZCode's native connectivity test with one real model request. - bb archive and rename actions work, with names and archive state kept in
bb (ZCode title generation stays off); clearing a thread goal calls the
native session goal action.
/zcode-pluginmanages ZCode's own plugins from bb. Native scheduled tasks (Cron tools) work with theautomationsEnabledsetting and run while bb is open. Full unified-diff views, cost billing and a full subagent tree remain unsupported. - Browser Use, interactive plugin UI, and Off-Peak/workflow host services need further integration; native attempts fail with a clear message pointing to ZCode Desktop.
- ZCode labels this session API as legacy while migrating its desktop protocol. Future CLI versions may require adapter changes.
See the capability audit for the full feature matrix, source evidence, verification limits, and recommended implementation order.
flowchart LR
BB["bb"] <-->|"Bridge v2 · deltas v3"| Plugin["bb-zcode"]
Plugin <-->|"Native protocol v1 · stdio"| CLI["ZCode CLI"]
CLI <-->|"ZCode configuration"| Model["Personal API / Coding Plan"]
The adapter translates the two protocols, supervises child processes, and forwards native approval requests to bb. bb instructions are prepended to the first prompt and retained in ZCode's saved conversation.
npm run check # TypeScript, tests, and bb's plugin builder
npm run format:check # Formatting
npm run test:live # Installed ZCode CLI + isolated loopback modelThe live test uses an isolated HOME and synthetic provider configuration. It does not use your model credentials. CI runs the static checks and synthetic test suite; the native CLI smoke is opt-in.
marketplace.json is generated from the package branding and
PLUGIN_OVERVIEW.md. Run npm run marketplace:build after changing either;
CI checks that the committed catalog stays in sync.
Contributions are welcome. Start with CONTRIBUTING.md and the configuration guide.
MIT © 2026 Dmitry Polishuk.
Built on the public bb plugin SDK and ZCode's native protocol. This is an independent community integration, not an official bb or ZCode plugin.