Use ZCode models, tools and conversations through Paseo's public Provider API. The plugin launches the official stdio Services Server from the integrated ZCode CLI distribution, which it can set up for you. Authentication, models, tools and conversation storage remain owned by ZCode. ZCode Desktop is not required.
Mode/Plan restoration is guaranteed when Paseo supplies both saved settings on resume. Without them, the pinned ZCode source can restore an older editing mode and drop Plan. That upstream defect remains unresolved and is outside the supported restoration contract. See verification and remaining checks.
This is an unofficial plugin. It is not endorsed or maintained by ZCode or Z.ai. The official RPC/V4 implementation is public source, but it is not a stable third-party SDK.
| Setting | Requirement |
|---|---|
| Paseo | 0.15.0 or later; development SDK 0.15.4 |
| Plugin Node.js | 22.12.0 or later (the Paseo daemon's runtime) |
| Managed setup | darwin-arm64, linux-x64, linux-arm64, win-x64, win-arm64 |
| ZCode | Managed: 3.17.2 (release 3.17.2-paseo.1) with Node.js 24.21.0. Overrides: stable Server 3.14.0+ / Agent 0.16.9+ with Node.js 24.14.0+ |
Enable Settings → Plugins → Enable plugins for the target daemon, then install the npm package and inspect:
paseo plugin add npm:paseo-plugin-zcode-provider
paseo plugin lsYou can also paste npm:paseo-plugin-zcode-provider into Settings → Plugins → Plugin source. npm packages require npm on the daemon host. Paseo installs the released version and compiles the plugin. Update with paseo plugin update zcode-provider. Plugins execute with the daemon user's permissions.
To follow the main branch instead, install the Git repository with paseo plugin add github:supermomonga/paseo-plugin-zcode-provider. The form without github: looks the plugin up in Paseo's plugin registry, which does not list it. Paseo prepares the checkout with npm ci.
Open Settings → Plugins → zcode-provider → Settings. The screen has three tabs: Runtime installs and removes the runtime, Account signs in and manages model providers, and Timeline chooses what ZCode agents add to the timeline.
On the Runtime tab, choose Download and install. The screen lists every download, its SHA-256, size and license before you start. Setup runs on the machine hosting the daemon:
- Node.js 24.21.0 from nodejs.org.
- The ZCode runtime 3.17.2 from this repository's releases (
3.17.2-paseo.1). ZCode does not publish its integrated CLI, so this is an unofficial build of the public source with the patches in patches/zcode applied (ADR 19), made and verified by CI. The patches hide Computer Use, Browser Use and Visualize, which cannot run or render here. It is not endorsed or maintained by ZCode or Z.ai.
Both archives are verified against SHA-256 values pinned in the plugin and extracted to the daemon user's data directory:
| OS | Destination |
|---|---|
| Windows | %LOCALAPPDATA%\paseo-plugin-zcode-provider\runtimes |
| macOS / Linux | ~/.local/share/paseo-plugin-zcode-provider/runtimes |
An absolute XDG_DATA_HOME replaces the base directory on every OS. PATH and other installations are not changed. The plugin never installs anything until you start setup.
Remove on the Runtime tab deletes the managed runtime; paseo plugin remove does not. ZCode settings, logins and conversations are kept.
The Account tab uses ZCode's own account and provider services, the same ones ZCode Desktop uses, through a ZCode Server that the plugin starts while the screen is in use. Changes are stored in ZCode's data on the daemon machine and are shared with ZCode Desktop and the CLI there.
- Sign in: choose Z.ai (international) or BigModel (China) and press Sign in. The sign-in page opens in your browser; the link is also shown, so you can finish on any device. The daemon receives the result, then selects the account's Coding Plan unless a plan is already chosen. The Plans section shows which of the account's plans (Coding Plan, Start Plan) are available. ZCode allows one signed-in account at a time.
- Model providers: add any number of providers that use an API key, from a ZCode template (Z.ai, BigModel, Kimi, MiniMax, DeepSeek, Alibaba Cloud, OpenAI, Anthropic, xAI, OpenRouter and others) or a custom endpoint with its base URL, API format and model IDs. Providers and models can be turned off, edited and deleted.
API keys are sent to ZCode, which stores them as Desktop does, and are never shown again. The plugin itself stores no credentials. Afterwards, choose ZCode when creating an agent; the model list is refreshed after each change.
ZCode adds a line when a turn runs on a different model than the previous turn, such as Model switched magpie/GLM-5.3-Flash → magpie/auto/glm-5.3-flash. These lines are hidden by default; turn on Show model changes on the Timeline tab to show them. The setting is stored by Paseo on the daemon host. It decides each line when the line first arrives: lines already shown stay, and lines that arrived while it was off are not added later. A reopened agent shows its history with the current setting (ADR 24).
Paseo's Usage screen and sidebar usage summary show a ZCode card for the signed-in account's Individual Coding Plan (Z.ai or BigModel). It lists the 5-hour, weekly, monthly tool-call and ZCode MCP quotas with their reset times, as ZCode Desktop does. The plugin asks ZCode's official usage service for this plan only, on the same ZCode Server as the Account tab. The service never uses an API key from the environment. Team Plan and Start Plan are not shown. Nothing is requested while Check usage is off for the host. Paseo 0.15.4 does not yet show usage in a ZCode agent's popover.
Set both variables in the daemon's environment and restart the daemon to bypass the managed runtime:
export PASEO_ZCODE_RUNTIME=/absolute/path/to/zcode # extracted integrated CLI distribution
export PASEO_ZCODE_NODE=/absolute/path/to/node # ordinary Node.js 24.14.0 or laterPASEO_ZCODE_RUNTIME must contain server/remote/zcode-server.cjs, agent/zcode.cjs, its provider configuration, and package.json. Setting only one variable is an error. Newer stable versions are allowed, including major versions; passing the minimum check does not certify compatibility. A terminal export does not change an already running Desktop application. Electron, process.execPath and Desktop discovery are never used.
Session environment variables are forwarded, subject to ZCode's own proxy, certificate and runtime environment handling. As Desktop does, the plugin sets ZCODE_APP_VERSION to the runtime's ZCode version, so model requests report it instead of the CLI's version.
The source baseline is a9fe401eede6e6e5e01be9048679c206fe6f02d9 (ZCode 3.17.2, upstream tag v3.17.2). The managed runtime passed the stdio runtime contract on all five managed platforms in CI. See the verification record for exact coverage.
- Models and reasoning options come from ZCode. Editing modes are
build,edit,guardedandyolo;settings.plan_modeis independent.guarded(ZCode's Autonomous mode, Server 3.15.1 or later) runs tools without approval but asks once, each time, before a command that ZCode's safety rules consider risky; it is not offered on older runtimes. - Text, thoughts, tools, subagent progress, usage and history use V4 snapshots and deltas. Tool output is marked when ZCode truncates it. Usage is cumulative; repeated snapshots do not add it again.
- Text submitted during generation uses native guidance. Attachments use the native queue. Paseo reports one run across these native turns and completes it only after all accepted input has been consumed and foreground work has ended.
- Paseo sends every message typed in the app during a run as a steer that asks to clear pending permissions. The plugin queues it first, then declines pending permissions, questions and Plan approvals with their deny action until ZCode reads the message, including requests opened in the meantime. Requests that appear after it is read are left to the user. Declining a Plan approval in Plan mode ends ZCode's turn; the message then starts the next native turn in the same Paseo run (ADR 22).
- A failed turn reports a code classified from the attribution of ZCode's error:
MODEL_RATE_LIMITED,MODEL_AUTH_FAILED,MODEL_CONTEXT_EXCEEDED,MODEL_NETWORK_ERROR,MODEL_PROVIDER_ERROR,MODEL_CONTENT_FILTEREDorMODEL_REQUEST_FAILEDwhen the model provider or network failed, andNATIVE_TURN_FAILEDotherwise. The message is the plugin's own text with the HTTP status and the provider's error code when known. The provider's own message, which can include a quota reset time, is not shown; Coding Plan reset times appear on Paseo's Usage screen (ADR 23). - Acceptance is reported once, after the native acknowledgement. Unknown delivery results are never automatically resent. Stop identifies the current native execution, disables automatic queue execution and removes pending input. A new explicit run enables the queue again.
/compact [instructions]compacts the conversation in a turn of its own; the instructions go to the summary request. ZCode adds no user message for that turn, so the plugin ties it to the command by the ID on the turn itself. Stop cancels a compaction in progress, although ZCode names no execution for it then (ADR 28).- As in ZCode Desktop, successful hooks are not shown. A finished hook invocation appears once, as a notification, only when a hook was blocked, failed, timed out or was cancelled; context compaction and a goal verification also appear once, when they end. Paseo appends every notification it receives, so progress is not reported. Model changes appear only when turned on (see Timeline).
- Native permission IDs, option values, questions and Plan approval retain their meanings. Question auto-resolution is disabled for each owned Server. Workspace hook trust is reviewed through the official CLI; it is not represented as “allow once.”
- From ZCode 3.17, a project's own MCP servers start only after they are trusted in ZCode Desktop (Settings → MCP Servers); ZCode has no CLI command for it. A session that uses the project's MCP configuration shows a warning while any of them awaits trust. MCP servers that Paseo passes to a session replace ZCode's MCP configuration, as before, and are marked as the user's, so the project's trust review does not block them.
- Each session owns its Server process and environment. Metadata requests use temporary Servers. Closing stdin gives ZCode time to clean up before process termination.
/goal <objective>sets a ZCode goal, as in ZCode Desktop: ZCode works toward it in turns it starts itself, verifies the result after each one and continues until the verifier passes it./goal replace <objective>(or a new/goal <objective>) replaces the goal, stopping the turn pauses it,/goal resumecontinues it, and/goal pausepauses a goal that is active without a turn. Goal commands need an idle agent and Plan mode off; ZCode does not run a goal in Plan mode. ZCode's Server has no command for/goal clearor/goal show, so the plugin refuses them with an explanation, and/goalwith an attachment (ADR 27).- An agent with a goal shows a Goal pill above the composer, next to Paseo's Tasks, with the time spent and an icon for the state. Its popover lists one row per iteration with the count of that iteration's tasks, as ZCode Desktop's status panel does. The pill follows the goal within about 10 seconds while it is in progress. It appears only while the agent's session is open: after Paseo released an idle agent or the daemon restarted, it returns with the next message.
- With Release idle agents (Host settings → Agents, on by default), Paseo closes an agent's session after an hour of inactivity and reopens it on the next message. The plugin keeps the session while ZCode still has a foreground turn, queued input, a pending question or approval, a running background command, subagent or workflow, or a goal that is active or being verified (ADR 25). A finished background command's result that ZCode has not yet delivered is not distinguishable and does not keep it. Resume agents after restart reopens agents interrupted by a host restart and sends the resume prompt. Both reopen the saved conversation with Paseo's saved mode and Plan settings (ADR 14).
The plugin uses ZCode's own skills, MCP configuration and tools. Browser Use and Computer Use cannot run in the plugin's ZCode, even when ZCode Desktop has them enabled: the Computer Use helper accepts only the signed Desktop app, and only Desktop provides browsers. ZCode's Visualize (interactive views in the conversation) renders only in Desktop. The plugin therefore hides all three from the model (ADR 19, ADR 21); Desktop is not affected. Generic rewind, independent Paseo child agents, hook-review UI, Workflow controls and buttons for the goal (use the /goal commands) are outside this migration. prompt.output_schema, custom system prompts and persist:false are unsupported. A system prompt makes session creation fail with INVALID_CONFIGURATION and a message explaining why, including one appended by Paseo's Orchestration → System prompt setting or by another plugin that adds one to new agents. MCP alwaysLoad is unsupported; stdio MCP commands must be absolute paths. Provider options are unsupported: agents.providers.zcode.options in Paseo's config.json makes sessions fail with INVALID_CONFIGURATION, and the command and env overrides there are not applied. Paseo does not show context usage reported before the first turn, and the plugin adds no substitute display; Coding Plan quota appears in Paseo's Usage screen (see Coding Plan usage).
New handles use version 3. Versions 1 and 2 are rejected without migration or replacement. Old Paseo sessions are outside this migration.
Unsent conversations are deferred drafts. Before the first prompt, the plugin atomically saves the logical-to-native ID mapping under $XDG_STATE_HOME/paseo-plugin-zcode-provider/sessions-v3, or ~/.local/state/paseo-plugin-zcode-provider/sessions-v3. It stores identifiers and workspace paths, not message bodies. Preserve this directory for backup. A mapping write failure prevents sending. Corrupt mappings and missing native conversations fail explicitly; no replacement conversation is created.
New conversations support listing, resume and paged V4 history. From ZCode 3.16, archiving belongs to Desktop's task list, so the listing also contains conversations archived in Desktop. Mode/Plan restoration requires both mode and settings.plan_mode saved by Paseo. The plugin applies them after native restore and confirms the resulting state before reporting the session ready. Omitted settings retain whatever ZCode returns, which can be stale on the pinned source; restoration of those values is not guaranteed. There is no private Plan restoration store. ADR 14 limits the guarantee to this supported path; settings-free restoration is checked separately with npm run test:native-restore. Existing ZCode databases may be migrated by ZCode itself on startup; the native tests isolate the home, configuration and database.
Settings → Plugins → zcode-provider → Diagnostics shows whether the managed runtime or the environment override is in use, the runtime and Node.js paths and versions, Server/Agent versions and hashes, minimum-version assessment and mapping location. The screen is read-only. Its optional version check does not prove that authentication or a model call succeeds. Settings → Providers also shows ZCode as not installed until the runtime is set up and supported. Its diagnostic lists the runtime source, Server, Agent and Node.js versions and platform, or the reason the runtime cannot be used. This check reuses its result for 30 seconds and does not start ZCode, so sign-in problems still appear when a session starts.
paseo plugin logs zcode-providerFor failures, report the operation, error code, structured diagnostic and versions/hashes. Native stderr, raw errors, credentials and conversation bodies are excluded from diagnostics. Review any additional material before sharing. Reports are not sent automatically.
See development, verification, remaining work, ADR 13, ADR 15 and ADR 19.
Original code is MIT. Vendored ZCode RPC/contracts retain their upstream license and provenance. The ZCode runtime releases are Apache-2.0 builds of the upstream source and include ZCode's LICENSE, NOTICE.md and THIRD-PARTY-NOTICES.md. Releases named <version>-paseo.<n> modify that source with the patches in patches/zcode (Apache-2.0), ship them in the archive and list them in BUILD-INFO.json; the earlier 3.14.3 release is unmodified; third-party components keep their own terms. Node.js is downloaded from nodejs.org, not redistributed. The icon retains Apache-2.0 attribution; the historical screenshot includes third-party UI and branding. See NOTICE.