TL;DR

ZCode (zai-org/ZCode) is the coding-agent harness that Z.ai (Zhipu) ships around its GLM models: an Electron desktop app, a browser workspace, and a zcode terminal agent, all driven by the same TypeScript runtime. It launched as a closed product on 2026-07-01, and became open source on 2026-09-21 under Apache-2.0. Two days later the repo has 6,458 stars and 1,906 forks, which puts it among the fastest-starred repos of the week.

The reason it is open source is the story. On 2026-09-18 a paying subscriber published a reverse-engineering report showing that ZCode 3.12.3 silently packaged entire workspaces, including .git history, encrypted them with a server-supplied key, and uploaded them to Alibaba Cloud storage. Z.ai acknowledged the uploads the same day, shipped 3.14.0 with the pipeline removed, and published the source so people could check.

Key facts:

  • License / language: Apache-2.0, TypeScript, pnpm monorepo. Version in package.json: 3.14.0
  • Requirements: Node.js 24.14.0 and pnpm 10.33.2 (pinned in mise.toml). There is no npm install -g zcode; you build the CLI distribution yourself or use Z.ai’s installer
  • Three front ends, one runtime: pnpm dev:desktop (Electron), zcode --web (browser UI on 127.0.0.1), and zcode (TUI). The agent CLI in apps/zcode-cli/ provides the runtime for all three
  • Agent features: four permission modes (build, edit, plan, yolo), seven lifecycle hooks, MCP over stdio/HTTP/SSE, a plugin system with skills and custom commands, subagents, memory, Node REPL, and a bundled Browser Use plugin
  • Model: built for GLM-5.3 ($1.40/M input, $4.40/M output; Coding Plan from $18/month). The two official Anthropic-compatible endpoints are silently rerouted through Z.ai’s gateway
  • What is missing: the repo has two commits and no history, Issues are disabled, there is no SECURITY.md, and the Computer Use package is a placeholder that returns “unavailable”

Verdict: a serious, feature-complete harness that you can now audit, arriving with a trust deficit that the code drop only partly repairs.

Quick reference

Repogithub.com/zai-org/ZCode
Stars / forks6,458 / 1,906 (2026-09-23)
LicenseApache-2.0 (first-party code; third-party notices separate)
LanguageTypeScript; Electron + React + Zustand; Node 24.14.0
InterfacesDesktop (Electron), Web (zcode --web), TUI (zcode)
ModelGLM-5.3 by default; any Anthropic-compatible or OpenAI-compatible provider via config
Data dir~/.zcode/ (CLI sessions in ~/.zcode/cli/db/db.sqlite)
Config~/.zcode/cli/config.json (MCP, hooks, plugins)
Docszcode.z.ai

What ZCode is

ZCode is Z.ai’s answer to Claude Code and the Codex app: a first-party harness tuned for the vendor’s own model, with a subscription (the GLM Coding Plan) that gives you more tokens if you use the vendor’s tool. On the July 2026 launch thread on Hacker News, the consensus was that the desktop UI is “basically an exact copy of Codex” and that the incentive to use it over OpenCode was quota, not features.

The open-source repo shows there is more underneath than a Codex-style shell. The monorepo has packages/desktop, packages/web, packages/server (HTTP/WebSocket plus remote connections), packages/services (business logic and persistence), shared protocol and RPC packages, provider abstractions, and apps/zcode-cli, which is the actual agent. Inside the CLI, packages/core/src/ is organised into agent, compact, context, hooks, mcp, memory, permission, subagent, workflow, tool, repl, embedded-search, and system-reminder. That list is a fair map of what a 2026 coding harness needs, and the total drop is 6,973 files and roughly 1.03 million lines, according to the researcher who audited it.

Two design choices stand out. First, the remote-workspace story is real: the desktop app can run the agent over SSH, WSL, or a container, uploading its runtime via SFTP and syncing provider credentials to the target. Second, codebase search is local. The runtime bundles ripgrep 14.1.1 and bfs 4.1.1 for symbol and file search, which matters because Z.ai’s original explanation for the uploads was that they were needed for indexing.

The timeline, from the primary sources:

  • 2026-09-18, morning (UTC+8). A developer writing as ferstar noticed ~/.zcode had grown past 700 MB and found a 313 MB .enc archive in v2/checkpoints/ with a state file listing 42,411 files from a commercial project, "kind": "baseline", and "failureCount": 564. Unpacking app.asar showed the flow: the client calls POST /api/v1/snapshot/upload-credential on zcode.z.ai, receives an RSA public key plus Alibaba Cloud OSS form credentials, tars and AES-256-CTR-encrypts the workspace, wraps the key with RSA-OAEP, and posts the blob straight to OSS. The private key never touches the user’s machine. The manifest showed 86.6% of the payload was .git: LFS cache, object store, and reflogs.
  • The toggles did not work. “Optimize Experience” only governed training consent; “Repo Snapshot Indexing” only governed server-side indexing. The capture sidecar was instantiated unconditionally at startup and triggered before every prompt.
  • What actually left the machine. The 313 MB archive failed 564 times because it exceeded a size limit and never uploaded. A smaller public-repo workspace (538 files, about 15 KB compressed) was accepted by the server. Other users reproduced the directory layout on Windows.
  • 2026-09-18, 17:44. Z.ai’s statement said the uploads came from “codebase indexing” used for Repo Wiki generation, that data was “destroyed immediately,” that the feature was on by default early on, that it was fixed, and that ZCode would be open-sourced with third-party review. Every user got one extra weekly quota reset.
  • 2026-09-21, 09:23. ZCode announced on X that remediation was complete, apologised, and published the repo. It cited audits from CAICT and NSFOCUS saying the zcode-prod bucket was empty and deleted, and that 3.14.0 contains no snapshot generation or upload path.

Ferstar’s post-release audit found that the upload endpoint, the OSS PostObject code, and the AES/RSA envelope code are gone from the public tree, and that the checkpoint feature Z.ai cited (packages/services/src/git/gitCheckpointService.ts) is a local git diff utility that stores JSON under ~/.zcode/checkpoints/ with no cloud dependency. The ferstar thread on Hacker News reached 339 points and 114 comments; the original X post passed 1.6 million impressions.

Key features, with the config that drives them

Permission modes

The CLI accepts --mode build|edit|plan|yolo. The shared runtime defaults to build. The important gotcha, spelled out in the project’s own NOTICE.md and visible in apps/zcode-cli/packages/cli/src/run.ts, is that headless runs default to yolo:

const DEFAULT_HEADLESS_PROMPT_MODE: CliPermissionMode = "yolo";

So zcode --prompt "fix the failing test" without --mode will approve ordinary tool calls on its own. Pass --mode build or --mode plan in scripts and CI.

Lifecycle hooks

Hooks live in ~/.zcode/cli/config.json and are off by default. Seven events are supported: SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, and Stop. Each hook is a process (argv, not a shell string) that receives one JSON object on stdin and may return one on stdout. Exit code 2 is an explicit deny; other failures are logged and do not crash the turn.

{
  "hooks": {
    "enabled": true,
    "timeoutMs": 60000,
    "events": {
      "PreToolUse": [
        {
          "matcher": "^(Bash|Write|Edit)$",
          "hooks": [
            { "type": "process", "command": "node", "args": ["./scripts/pre-tool-hook.mjs"], "timeoutMs": 5000 }
          ]
        }
      ],
      "Stop": [
        { "hooks": [{ "type": "process", "command": "node", "args": ["./scripts/stop-hook.mjs"] }] }
      ]
    }
  }
}

A PreToolUse hook can block with:

{
  "continue": false,
  "reason": "Do not run destructive shell commands in this workspace.",
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Blocked by project hook."
  }
}

A Stop hook can return continue: true with additionalContext to force one more model step; repeated continuations are capped to avoid loops. If you have written Claude Code hooks, the shape will feel familiar.

MCP servers

MCP is enabled by default and reads from mcp.servers in the same config file. The CLI does not auto-discover a project-level .mcp.json outside of enabled plugins.

{
  "mcp": {
    "servers": {
      "filesystem": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
        "timeoutMs": 30000
      },
      "docs": {
        "type": "http",
        "url": "https://mcp.example.com/mcp",
        "headers": { "Authorization": "Bearer <token>" }
      }
    }
  }
}

Tools are exposed as mcp__<server>__<tool>, and /mcp list, /mcp status, /mcp connect <server>, and /mcp disconnect <server> manage them in a session.

Plugins, skills, and commands

Plugins are local bundles with a .zcode-plugin/plugin.json manifest declaring skills (folders of SKILL.md), commands (markdown custom commands), mcpServers (inline or via .mcp.json), and userConfig. Four official plugins ship enabled: Browser Use, Document Skills, Skill Creator, and ZCode Guide. Heavier ones such as ios-simulator and android-emulator are discovered but disabled until you run zcode plugins enable ios-simulator. Only ZCODE_-prefixed environment variables expand inside plugin config, and a missing variable disables that MCP server rather than failing silently.

Getting started

There is no published npm package. You either clone and build, or use the installer Z.ai hosts for its own distribution.

git clone https://github.com/zai-org/ZCode.git
cd ZCode
# Node 24.14.0 + pnpm 10.33.2; mise.toml is the source of truth
pnpm bootstrap                       # install deps, prepare desktop assets, build

To run the agent from source:

pnpm --filter @zcode/cli dev --help
pnpm --filter @zcode/cli... build
node apps/zcode-cli/packages/cli/dist/zcode.cjs --help

To build the unified zcode CLI distribution (TUI + Web + agent, no Electron):

ZCODE_DIST_BASE_URL=https://downloads.example.com/zcode/ pnpm build:zcode
zcode_version=$(node -p "require('./dist/zcode/latest.json').version")
mkdir -p dist/zcode/debug
tar -xzf "dist/zcode/releases/$zcode_version/zcode-$zcode_version.tar.gz" -C dist/zcode/debug
node dist/zcode/debug/zcode/bin/zcode.mjs                    # TUI
node dist/zcode/debug/zcode/bin/zcode.mjs --web --port 3030  # browser UI

Web mode binds 127.0.0.1 with no token by default. Use --host 0.0.0.0 for LAN access; a token is generated automatically when you bind a non-local address, and --no-token turns it off.

For the desktop app, pnpm dev:desktop runs it against production services; pnpm bundle:desktop -- --os linux --arch x64 produces installers. Local macOS builds are unsigned, so expect sudo xattr -rd com.apple.quarantine /Applications/ZCode.app on first launch.

Community reaction

The July launch thread and the September incident thread read like two different products.

In July, the criticism was strategic. “I’m somewhat surprised that this is not open source,” one commenter wrote, pointing at Xiaomi’s MiMo-Code. Another replied that harnesses “are not just wrappers, and often they contain business logic that is not suitable for public distribution.” A third: “UI-wise this looks a lot closer to Codex than Claude Code. It’s basically an exact copy of Codex.” Linux support on day one got real praise.

In September, the tone was anger and vindication. “Closed source agents are a red flag no matter if it’s China or America. Always use an open harness with a good reputation and enough users that someone will notice if they push malicious code.” One user who had just bought a month of GLM called it “pretty gutting” while admitting “ZCode is honestly one of the best harnesses out there from an HCI perspective.” The most quoted line: “The funniest thing is that the uploaded content is encrypted using a key that the users don’t have.”

Several commenters noted that OpenCode and Grok’s harness had their own scanning and upload incidents this year. The takeaway most people landed on: the harness is part of the trust boundary, and only open harnesses let you check it.

Honest limitations

  • Two commits, no history. The public tree is an empty initial commit plus one 1.03M-line feat: open source commit. You cannot diff 3.12.3 against 3.14.0 to see how the snapshot pipeline was removed; you can only confirm it is absent now.
  • Issues are disabled and there are no accepted pull requests. Community channels are Discord and Feishu. This is a code drop, not (yet) a community project.
  • No SECURITY.md. The repo launched without a security policy or private-reporting path, which is a strange omission for a release motivated by a security incident.
  • Client source cannot prove server behaviour. The NOTICE.md says outright that gateway-side processing is outside what the repo verifies. Whether pre-Sep-18 snapshots were purged rests on the CAICT and NSFOCUS summaries, whose full reports were still “to be published” at launch.
  • Gateway rerouting. Requests to two official Anthropic-compatible endpoints are matched by host and path and re-sent through Z.ai’s gateway, headers and auth included, with no per-request confirmation. The origin is configurable via ZCODE_BASE_URL, but you need to know it is happening.
  • No OS sandbox. Per the notice, the shared execution adapter provides no default sandbox; worktrees and REPL contexts are not isolation guarantees.
  • Headless defaults to yolo. Covered above; easy to miss.
  • Credential storage is encrypted files, not the OS keychain, with a default key derivable from machine environment. Web OAuth tokens can live in localStorage.
  • Computer Use is a stub. packages/zcode-cua returns an “unavailable” error.
  • Docs are Chinese-first. The root README defaults to Chinese with an English mirror; AGENTS.md, NOTICE.md, and config/README.md are Chinese only.
  • Build toolchain is strict. Node 24.14.0 and pnpm 10.33.2 exactly; no prebuilt binaries in the repo.

If you ran 3.12.3 or earlier, ferstar’s tripwire is still worth setting even on 3.14.0, because the desktop client can hot-update: chflags uchg ~/.zcode/v2/checkpoints on macOS or sudo chattr +i ~/.zcode/v2/checkpoints on Linux.

Who should use ZCode

Good fit:

  • GLM Coding Plan subscribers who want the quota advantages of the first-party harness and can now read what it does
  • Teams that need a remote-workspace agent over SSH/WSL/containers with a desktop front end
  • Developers who want a Claude-Code-style hook and plugin system in an Apache-2.0 codebase they can fork
  • Researchers studying how a production harness is structured (permission service, compaction, memory, subagents, workflow runtime are all there)

Poor fit:

  • Anyone with proprietary code who is not prepared to audit or sandbox the client. Trust has to be re-earned on evidence
  • People who want a maintained community project with issues and PRs
  • Users who want a lightweight, model-agnostic CLI. OpenCode or pi are simpler if GLM quota is not the draw

Comparison with alternatives

ZCodeOpenCodeClaude CodeCodex CLIMiMo-Code
SourceApache-2.0 (since 2026-09-21)MITClosedApache-2.0Open (CLI)
Default modelGLM-5.3AnyClaudeGPTMiMo
InterfacesDesktop + Web + TUITUI + webTUI + IDETUI + appCLI
Hooks7 events, process-basedPlugins/eventsHooksLimitedLimited
MCPstdio/HTTP/SSEYesYesYesYes
Remote workspacesSSH/WSL/container built inVia terminalSSH via IDENoNo
CommunityIssues off, Discord/Feishu950+ contributorsVendorVendorVendor

ZCode’s strongest unique feature is the integrated remote-workspace flow; its weakest position is community trust and process.

FAQ

Is ZCode fully open source now? The desktop app, web client, backend server, shared UI, and the agent CLI/runtime are in the repo under Apache-2.0. Third-party binaries, fonts, and assets keep their own licenses, and Z.ai’s gateway, account, and billing services are not included.

Does ZCode still upload my repository? Not in 3.14.0 according to both Z.ai’s audits and an independent review of the source: the upload-credential endpoint returns 404 and the encryption and OSS code are gone. Versions 3.12.x and earlier did package and attempt to upload full workspaces, and the UI toggles did not stop it.

Can I use ZCode with models other than GLM? Yes. The provider layer supports Anthropic-compatible and OpenAI-compatible endpoints via configuration (ZCODE_BUILTIN_PROVIDER_CONFIG_FILE overrides the built-in list). Be aware that requests to the two official Anthropic endpoints are rerouted through Z.ai’s gateway unless you change the origin.

How much does GLM-5.3 cost through ZCode? API list price is $1.40 per million input tokens and $4.40 per million output ($0.26 cached). The GLM Coding Plan starts at $18/month with off-peak discounts. Some resellers list $1.09/$3.43. GLM-5.3 Flash is $0.15/$0.50.

Is there a Homebrew or npm install? No. Build the CLI distribution with pnpm build:zcode, or use Z.ai’s hosted installer, which places the runtime in ~/.zcode/runtime and a zcode shim in ~/.local/bin.

Bottom line

As software, ZCode is a well-built harness: a clean core with permission, hook, MCP, subagent, and workflow subsystems, three front ends on one runtime, and a remote-workspace mode that most rivals lack. As an open-source project, it is a defensive code drop, released to end an incident rather than to start a community. Both things are true. If GLM quota is why you would run it, you now have the ability, and the obligation, to read what it does before you point it at private code.

Sources