ZCode provider for pi

Use your ZCode / Z.ai Coding Plan directly in pi—no ZCode desktop app or zcodex app server required.

This extension connects pi directly to Z.ai's OpenAI-compatible Coding Plan endpoint. ZCode is optional, not a runtime dependency. It supports streaming, tool calls, GLM reasoning controls, image input on GLM-5.3 Flash, and browser-based sign-in.

[!WARNING] The ZCode authentication flow was derived from the desktop application and is not a documented public integration. Z.ai can change or disable it. See PROTOCOL.md for the protocol details.

Features

• Connects directly to Z.ai; no ZCode desktop app or zcodex app server required.
• Uses an existing ZCode desktop login automatically when available.
• Supports browser sign-in from pi with /login zcode.
• Accepts manually entered keys and ZCODE_API_KEY.
• Reuses or creates the account key named zcode-api-key.
• Prompts for an organization and project when the account has more than one.
• Registers the current Coding Plan GLM model catalog with zero metered cost in pi.

Requirements

• pi with package support
• Node.js 22.19 or newer
• A ZCode / Z.ai Coding Plan subscription

Install

Install from npm:

pi install npm:pi-zcode-provider

Reload an existing pi session:

/reload

Verify that the package is installed:

pi list

To test a local checkout without installing:

pi -e /absolute/path/to/zcode

[!IMPORTANT] This project is named pi-zcode-provider. The npm package zcode-provider is unrelated and uses the ZCode app server instead of the Coding Plan API.

Authenticate

The provider resolves credentials in this order:

1. A key saved by pi in ~/.pi/agent/auth.json
2. ZCODE_API_KEY
3. The desktop key in ~/.zcode/cli/config.json

Existing ZCode desktop login

If the ZCode desktop app is already signed in on the same machine, start pi and select a zcode/* model. The extension reads the Coding Plan key from the desktop configuration; no additional login is required.

Browser sign-in

Run pi, then open the login menu:

/login zcode

Choose Sign in with ZCode. Pi opens the Z.ai authorization page and waits for the login to complete. The extension then:

1. Exchanges the browser session for a Z.ai business token.
2. Finds the account organization and project.
3. Reuses or creates the API key named zcode-api-key.
4. Stores the resulting permanent key in pi's auth file.

The browser flow expires after five minutes. Accounts with multiple organizations or projects receive a selection prompt before the key is provisioned.

API key

Choose ZCode API key from /login zcode, or set the key before starting pi:

export ZCODE_API_KEY="id.secret"
pi --provider zcode --model glm-5.3

ZAI_API_KEY is intentionally not used. It may be a metered API key rather than a Coding Plan subscription key.

Use

Start pi with a model directly:

pi --provider zcode --model glm-5.3

Or start pi normally and use /model to select a zcode/* model. Available thinking levels depend on the selected GLM model.

Models

The provider registers the models advertised by the Coding Plan /models endpoint:

Model	Context	Maximum output	Input
glm-5.3	1M	128K	Text
glm-5.3-flash	1M	128K	Text, image
glm-5.2	1M	128K	Text
glm-5.1	200K	128K	Text
glm-5-turbo	200K	128K	Text
glm-5	200K	128K	Text
glm-4.7	200K	128K	Text
glm-4.6	200K	128K	Text
glm-4.5	128K	128K	Text
glm-4.5-air	128K	128K	Text

Coding Plan usage is recorded with zero per-token cost because access is subscription-based.

Security

[!CAUTION] API keys grant access to your Z.ai account. Do not commit or share them.

• ZCode stores its desktop Coding Plan key in plaintext at ~/.zcode/cli/config.json.
• Pi stores authenticated credentials at ~/.pi/agent/auth.json with user-only permissions.
• The extension never prints keys, business tokens, or authorization headers.
• Authorization URLs are restricted to HTTPS hosts under z.ai.
• The generated API key is permanent until it is revoked in Z.ai.

Troubleshooting

ZCode is missing from /login

Confirm that the local package appears in pi list, then run /reload. If it is still missing, start pi once with the extension explicitly:

pi -e /absolute/path/to/zcode

ZCode models are missing

Models become available after pi resolves a credential. Complete /login zcode, set ZCODE_API_KEY, or sign in with the ZCode desktop app. Then check provider registration outside the interactive UI:

pi -e /absolute/path/to/zcode --list-models | grep '^zcode'

If the extension reports a module error, run npm install in the package directory and retry.

Browser login expires

Run /login zcode again and complete the browser authorization within five minutes.

Remove the unrelated npm package

If pi list shows npm:zcode-provider, remove it unless you also use that separate integration:

pi remove npm:zcode-provider

Development

Install dependencies and run the complete check:

npm install
npm run check

npm run check runs TypeScript validation and the Vitest suite. The tests cover credential precedence, OAuth polling and expiry, endpoint request order, response envelopes, organization/project selection, API-key reuse and creation, secret redaction, model metadata, and pi provider registration.

Project structure

extensions/zcode.ts  pi extension entry point
src/provider.ts      native provider registration
src/auth.ts          login, credential resolution, and key provisioning
src/models.ts        GLM catalog and compatibility metadata
test/                authentication and provider regression tests
PROTOCOL.md          reverse-engineered ZCode protocol notes