ZCode Agent Kit

English | 中文 | Español | 日本語 | Deutsch

Use your own ZCode Desktop account with a coding assistant of your choice. The kit connects supported assistants to a local proxy; it does not install those assistants, create an account, buy quota, or provide free/unlimited access.

• Model proxy: OpenAI Chat Completions, Responses, and Anthropic Messages formats at http://127.0.0.1:8457 by default.
• Models: glm-5.3 (text) and glm-5.3-flash (text and images). Advertised context: 1M tokens; reasoning levels: low, high, max. Client support and account limits still apply.
• Optional MCP bridge: exposes operations of your installed ZCode runtime. This is separate from model-provider configuration. A running Desktop app does not guarantee standalone MCP model turns; the provider can reject them independently.

1. Before you install

You need:

1. ZCode Desktop, already signed in to your own account with available model quota.
2. Node.js 20 or newer, installed and available in your terminal: nodejs.org.
3. Bun for npm/source installs, available on PATH: Bun installation. The tested version is 1.4.2. npm/source setup uses Bun to install dependencies; it does not install Bun itself. Release installers can bootstrap Bun and record its absolute path.
4. Your chosen assistant, installed separately: OMP, pi, Claude Code, Codex, OpenCode, Cline, Kilo Code, Aider, Continue, or Goose.

Open a new terminal and check:

node --version
bun --version

These checks work in PowerShell and POSIX shells. Node must be available for every method; bun --version must work before npm/source setup. Release installers can download Bun when absent, save its absolute executable path in .bun-path, and reuse that path after restart without changing global PATH. Existing Bun installations are reused, not automatically upgraded.

Windows: use PowerShell, without administrator rights. Do not run install.sh in Git Bash or WSL. macOS/Linux: use a POSIX shell; curl, tar, a SHA-256 utility, and rsync for updates are needed; Bun bootstrap also needs unzip. Linux/macOS live-client support has not been reverified in the Windows validation described below.

2. Install once — choose one method

Avoid mixing npm and release-installer copies. They can have different local keys, while both modify the same assistant profile.

Recommended: published release installer

Run from any directory. You do not need to clone the repository or enter an installation folder. These commands download and execute the repository's published installer; inspect the script first if your policy requires it.

Windows — PowerShell:

irm https://github.com/ZepiGit/ZCode-Agent-Kit/releases/latest/download/install.ps1 | iex

macOS/Linux — POSIX shell:

curl -fsSL https://github.com/ZepiGit/ZCode-Agent-Kit/releases/latest/download/install.sh | sh

or

npm installation:

Requires both Node and Bun already on PATH. From any directory:

npm install -g zcode-agent-kit
zcode-kit setup

In the current source, npm postinstall prints a hint; explicit setup performs integration. Older published packages may behave differently. The npm command names are zcode-kit and zcode-agent-kit. A 404 can mean the requested package/version is unavailable or inaccessible; it does not prove a local installation fault.

Do not use a transient npx ... setup as a permanent installation: generated configurations refer to the package's filesystem location. Use a stable global install or the release installer.

The installer verifies the release archive's SHA-256, installs locally, and runs setup. Defaults:

ZCODE_KIT_INSTALL_DIR overrides ZCODE_KIT_HOME; otherwise the default is used. Always choose a dedicated absolute directory. Never choose your home directory, working project, or source checkout: installer updates replace/mirror files there. These variables select the installer destination; setting them later does not redirect an already-installed CLI.

For reproducibility, set ZCODE_KIT_VERSION to an existing release tag, including its v prefix, before running the installer. Remove the override when you want latest again. Changing that variable pins the archive; the one-liners above still fetch the installer script from the latest release.

3. Verify which installation you are using

After installation, open a new terminal and run:

PowerShell:

Get-Command zcode-kit -All
node --version
bun --version
zcode-kit help

macOS/Linux:

command -v zcode-kit
node --version
bun --version
zcode-kit help

If zcode-kit is not found, the shim directory above may be missing from PATH. Add the correct directory to your shell/user PATH, then reopen the terminal. If multiple copies exist, use the explicit path below rather than guessing which copy is active. PowerShell and Git Bash may select different copies on Windows.

Explicit paths: safe from any working directory

Define the path to the installation you actually chose, once per terminal session. The defaults below are for release-installer installations, not npm. Replace the assignment for a custom destination or source checkout.

PowerShell:

$KitRoot = Join-Path $env:LOCALAPPDATA 'zcode-agent-kit'
if (-not (Test-Path (Join-Path $KitRoot 'cli/zcode-kit.mjs'))) { throw 'Wrong KitRoot: cli/zcode-kit.mjs not found' }
node (Join-Path $KitRoot 'cli/zcode-kit.mjs') help

macOS/Linux:

KIT_ROOT="$HOME/.local/share/zcode-agent-kit"
if [ -f "$KIT_ROOT/cli/zcode-kit.mjs" ]; then
  node "$KIT_ROOT/cli/zcode-kit.mjs" help
else
  printf '%s\n' 'Wrong KIT_ROOT: cli/zcode-kit.mjs not found' >&2
fi

If the check fails, stop and correct the path. For npm, npm root -g identifies the global modules directory; the kit is its zcode-agent-kit subdirectory. Do not substitute a release-install path for an npm copy.

Do not type node cli/zcode-kit.mjs from an arbitrary directory. Relative paths refer to the current directory, not the kit. The global shim or absolute script path avoids this problem.

4. Configure and make the first model call

Setup detects assistants from executables/configuration directories and applies their adapters. Detection does not prove that a client is installed or working. To configure a selected assistant instead:

zcode-kit setup --harness omp
zcode-kit integrate continue --dry-run

Use these only after verifying the command's installation in section 3. Setup can modify user-level assistant configuration and MCP registrations. It records configuration transactions, but it is not an all-or-nothing operation: a later failure leaves earlier successful changes in place and prints a rollback command.

Current-source setup also makes one small live Flash request, which can consume quota. To skip it, set ZCODE_KIT_SKIP_SMOKE=1 for that invocation; CI/test modes skip it too. If configuration was saved successfully but the API attempt fails, setup reports a warning and keeps the configuration success; that is not evidence of a successful model turn. doctor --fix does not install missing dependencies or perform general setup.

zcode-kit status
zcode-kit doctor
zcode-kit auth status
zcode-kit usage --json

A stopped proxy can make diagnostics fail before first launch. Start it as described in section 6 or launch an assistant that auto-starts it. A health check or exit code alone does not prove model access: inspect logged_in, quota diagnostics, and an actual model reply.

Run assistants in your project — not the kit directory

Open a terminal inside the project you want the assistant to work on, or use Set-Location (PowerShell) / cd (POSIX) to enter that project. The kit launchers preserve that working directory.

OMP, direct command (not zcode-kit run omp):

omp -p --model zcode/glm-5.3-flash "Reply with 52"
omp -p --model zcode/glm-5.3 "Reply with 52"

Expected: a model reply of 52, exit 0. Normal latency varies; a timeout still counts as a failed attempt. For interactive use:

omp --model zcode/glm-5.3 --thinking max

Other kit launchers — everything after -- is passed to the assistant:

zcode-kit run claude-code -- -p "Reply with 52" --model glm-5.3-flash
zcode-kit run codex -- exec "Reply with 52" -m glm-5.3-flash
zcode-kit run aider -- --model openai/glm-5.3-flash
zcode-kit run opencode -- .

Model identifiers always use /, including on Windows. run supports only claude-code, codex, aider, and opencode. OMP's extension and those launchers start/check the proxy; start it manually for other clients.

5. What each integration does