A Pi extension for running Z.AI with visible cache behavior, native thinking diagnostics, and local operator metrics.
Pi already owns the agent loop, tools, sessions, streaming, and Z.AI provider. pi-zai hooks into that existing path. It does not proxy chat traffic, replace Pi's runtime, or create a second model client.
pi install npm:@onlinechefgroep/pi-zaiAlso published to GitHub Packages (see Getting started for the authenticated @onlinechefgroep registry setup).
Reload Pi, select a Z.AI model, and open the status view:
/reload
/zai
Credentials stay in Pi's normal credential flow: /login, auth.json, models.json, or ZAI_API_KEY.
| Area | Native Pi + Z.AI | With pi-zai |
|---|---|---|
| Agent runtime | Pi | Still Pi |
| Provider and streaming | Pi's native Z.AI provider | Still Pi's native provider |
| Thinking | Pi selects and maps the level | Actual request fields are shown; optional explicit override only |
| Cache visibility | Usage fields are available internally | Full Z.AI session totals plus current-segment diagnostics |
| Diagnostics | General provider errors | /zai-doctor, transport summaries, retry guidance |
| Usage | Per-response usage and Pi Session Info | Z.AI-scoped totals, Coding Plan quota, Platform estimates |
| History | Session-scoped | Privacy-reduced local SQLite metrics |
| Command | Purpose |
|---|---|
/zai |
Provider, endpoint, model, actual thinking payload, cache, throughput, tools, and Z.AI session usage |
/zai-cache |
Current cache segment, hit/miss ratios, fingerprints, and recommendations |
/zai-usage |
Z.AI session token totals, Coding Plan quota, or Platform cost estimates |
/zai-doctor |
Integration checks and optional connectivity/stability probes |
/zai-capabilities |
Capability resolution and opt-in live probes |
/zai-transport |
Local latency and controlled error-category summaries |
/zai-data |
Inspect, export, vacuum, or wipe local metrics |
/zai-privacy preview |
Show exactly what is stored locally and what could be aggregated |
/zai-benchmark |
Track A0–A3 cache-strategy experiments |
pi-zai uses Pi's own thinking selector. There is no second /zai-thinking state to keep in sync.
For the current Pi GLM-5.2 catalog:
Pi off → thinking disabled
Pi low / medium / high → reasoning_effort high
Pi max → reasoning_effort max
Current Pi releases send clear_thinking=false while Z.AI thinking is enabled. pi-zai now leaves that native payload unchanged by default. An explicit preserveThinking: false setting can force clear_thinking=true, but this may reduce reasoning continuity and cache reuse in long coding/tool sessions.
The chat request still follows the normal Pi route:
You → Pi agent runtime → Pi native Z.AI provider → Z.AI API
pi-zai adds lifecycle hooks for request inspection, optional explicit policy overrides, cache analysis, headers, diagnostics, and local metrics. It does not upload prompts or completions through a separate service.
Pi's Session Info shows the complete session across all models and providers. /zai scans that session but includes Z.AI providers only. /zai-cache is intentionally narrower: it shows the current provider/model/system-prompt/toolset segment and resets when one of those boundaries changes.
This distinction prevents a model switch, extension reload, or new prompt/tool fingerprint from being presented as one continuous cache population. All-zero usage records from connection failures are ignored as cache samples.
Local metrics are enabled by default and stored under Pi's user directory:
~/.pi/agent/state/pi-zai/metrics.sqlite3
~/.pi/agent/state/pi-zai/local.secret
Stored fields are limited to operational data such as token counts, latency, HTTP status, controlled error categories, local hashes, and short fingerprints. Prompt text, source code, tool arguments, tool results, and raw error bodies are not stored.
Retention is bounded and the data can be removed from Pi:
/zai-data clear-project
/zai-data clear-details
/zai-data clear-all
Anonymous aggregate telemetry exists as an opt-in path and is off by default. It requires both configuration and explicit consent.
{
"zai": {
"sessionAffinity": "off",
"promptStability": { "mode": "observe" },
"metrics": { "mode": "local" },
"telemetry": { "mode": "off" }
}
}| Setting | Default | Meaning |
|---|---|---|
preserveThinking |
omitted | Leave Pi's native request unchanged; true or false are explicit overrides |
metrics.mode |
local |
off, in-memory, or bounded SQLite storage |
promptStability.mode |
observe |
Measure stable and volatile prompt sections without rewriting |
sessionAffinity |
off |
Experimental X-Session-Id support when enabled |
adaptiveTools.mode |
off |
Opt-in adaptive tool loading (observe / manual) |
telemetry.mode |
off |
No remote aggregate uploads |
| Provider | Base URL | Billing |
|---|---|---|
zai |
https://api.z.ai/api/coding/paas/v4 |
Coding Plan (global) |
zai-coding-cn |
https://open.bigmodel.cn/api/coding/paas/v4 |
Coding Plan (China) |
zai-platform |
https://api.z.ai/api/paas/v4 (manual models.json) |
Metered Platform API |
pi-zai does not override Pi's built-in zai or zai-coding-cn providers. Register zai-platform in models.json only when you need the metered endpoint. Adaptive tools, cache segmentation, and /zai-capabilities follow whichever of these models is active.
- Getting started
- Architecture
- Cache optimization
- Thinking
- Commands
- Configuration
- Security and privacy
- Troubleshooting
- Development
npm install
npm run build
npm test
npm run lintThe extension targets Pi >= 0.80.10 and Node.js >= 22.19.0.
MIT — see LICENSE.