Last week I found a card in Orca’s settings: GLM Coding Plan, plan site set to Zhipu BigModel, API key showing Saved, and three usage rows underneath — 5-hour window at 5%, weekly at 92%, MCP monthly at 26%.

I paused. Since when did Orca support ZCode as an agent?

Following that thread turned out to be more interesting than “they added an agent.” From the first issue to the release, 63 days passed, and six separate PRs were all closed without merging. What finally landed the work was Z.ai open-sourcing ZCode on September 20.

One note before we start: I wrote about ZCode’s privacy problems earlier (the encrypted snapshot thing). This post is only about integration. Two separate questions — whether a tool can be wired into another tool, and whether it uploads your files behind your back.

Timeline: two months stuck, five days after the source dropped

In UTC:

WhenWhat happened
July 25Issue #10564 asks for ZCode as a first-class agent
July 26First PR, #10654, opened
Mid-August to mid-September#13965, #14556, #16227, #16228 all opened and all closed unmerged
September 20One more attempt, #21756
September 20, later that dayZ.ai open-sources zai-org/ZCode under Apache-2.0
September 25PR #22464 merges to main
September 26, 22:36 UTCv1.4.214 ships — ZCode becomes a first-class harness
September 27The site changelog lists “ZCode agent harness” as the headline of v1.4.215

One detail worth noting: v1.4.214 and v1.4.215 are one day apart because 1.4.215 is 1.4.214 plus a single profile fix. The site changelog picked the later number, which is why the “official” announcement reads September 27.

Follow-ups filled in the rest:

  • v1.4.218: ZCode session history lands in AI Vault, Coding Plan quota appears in usage
  • v1.4.221: you can link a GLM Coding Plan without installing ZCode at all (that is the card in my screenshot)
  • v1.4.229: sign-in reuses the existing setup terminal, conversations read in recorded order
  • v1.4.232: the GLM key can be stored on a remote host

The real blocker: evidence, not code

The PR writeup makes it clear that the six earlier attempts died on two things nobody could prove.

The first was provenance. Review on #21756 objected that zcode might just be an unofficial third-party client, and labeling it as Z.ai’s agent would be inaccurate. Before the source was public, nobody could answer that — you could only point at some binary on someone’s machine and say “probably fine.”

The second was worse: do the hooks actually fire?

ZCode supports hooks in ~/.zcode/cli/config.json, and there was an open bug report (zai-org/feedback#32) saying configured hooks never fired. Orca’s whole status system rests on hooks — the sidebar dot, the action-required badge, the completion notification all depend on the agent POSTing lifecycle events. If hooks never fire, wiring ZCode in gives you a panel that permanently reads “idle.”

Every one of those six PRs built its state machine on the assumption that hooks work. And you cannot code-review an assumption.

Open-sourcing answered both questions at once. Five days later, the PR author put it plainly:

written against the real source (agent CLI 0.16.9) rather than guessed at.

Six things reading the source changed

The #22464 writeup lists six findings that changed the implementation after reading the source. This is the most informative part of the whole story — nearly every one of them is a place where somebody had already guessed wrong.

One: ZCode’s hook payloads already carry Claude-compatible aliases.

Next to its own camelCase fields, ZCode’s hook runner writes a Claude-shaped set: hook_event_name, session_id, tool_name, tool_input, transcript_path, last_assistant_message. The source comments say this is deliberate.

So Orca needed no new parser. ZCode routes through the existing Claude-compatible vendor path and only needs its own identity. That also explains why six PRs kept churning the same code: everyone assumed a separate adapter layer was required. It wasn’t.

Two: hooks.enabled defaults to false.

That is the actual cause of “configured hooks never fire.” Declaring hooks.events isn’t enough; the runtime was never switched on. Orca’s installer sets the flag, and if a user later turns it back off, the status check reports partial instead of pretending everything is fine.

In short: nothing was broken. It was never plugged in.

Three: PermissionRequest only fires once the approval card is already on screen.

This one is valuable. The event races the user’s answer and can never fire for an auto-approved call — so it’s a trustworthy signal that the pane is blocked.

Compare that to agents where the equivalent event fires along several paths and you end up guessing with timeouts.

Four: ZCode’s clarification tool is literally AskUserQuestion, with Claude’s exact shape.

A questions array, an options array. Orca reuses its existing question card with zero new UI.

Five: it renames its own process to zcode-cli.

So process recognition cannot match the launch command. Without the source, you find this out from users reporting “the pane won’t detect the agent.”

Six: it emits no OSC title at all, and its banner animates forever.

Terminal programs normally write their title with an OSC sequence, and agents use that to decide what’s running. ZCode sends none, and repaints its banner continuously.

So readiness can’t wait for the screen to go quiet; it waits for the composer box to appear. The PR even keeps a test that pins down the negative result, so nobody re-attempts screen scraping.

Local test: the desktop app’s bundled CLI can’t open a TUI

Since I was already in the weeds, I checked my own machine.

  • Orca: 1.4.245
  • ZCode desktop: 3.17.1
  • zcode on PATH: none

That last one is the point. The ZCode desktop app ships an engine inside the bundle:

node /Applications/ZCode.app/Contents/Resources/glm/zcode.cjs --version
# 0.17.1

The version prints. Everything looks fine. Then try to open a session:

node /Applications/ZCode.app/Contents/Resources/glm/zcode.cjs tui
# Error: Cannot find package '@zcode/tui' imported from
# /Applications/ZCode.app/Contents/Resources/glm/zcode.cjs

The reason is simple: the desktop build ships the engine without the text interface, because it draws its own window and never needs one. Version, doctor, one-shot prompts all work. Only sessions fail — and sessions are exactly what Orca wants.

Orca later added a specific notice for this (PR #22730). It deliberately does not match the “TUI requires an interactive terminal” message, because that string is localized and Chinese users would never hit the rule; it matches Node’s module-resolution error, Cannot find package '@zcode/tui', which is never translated.

So the official requirement is written plainly in the docs: install a zcode build with a terminal UI. A terminal build, not the desktop app.

Another trap: which file the hooks live in

Orca’s docs say it writes hooks into ~/.zcode/cli/config.json. On my machine that file is 565 bytes with no hooks section and no setting.json next to it.

That’s expected — I never installed the CLI, so the installer never ran.

But a Windows user’s report in the issue is worth remembering: current zcode-app-cli (3.15.x and later) no longer reads hooks from config.json. That file is now a legacy/migration source; ~/.zcode/cli/setting.json is what actually takes effect. He hand-wrote the same hook structure into setting.json, the startup log’s hookCount went from 0 to normal, and events started firing.

The same report has three more details:

  • zcode login zai completing OAuth is not enough. For account:* providers the CLI additionally requires a Coding Plan API-key credential; with browser auth alone, every turn fails with Model creation failed. You have to run /login in the TUI, pick “Z.AI Coding Plan API Key,” and paste the key.
  • With the desktop app running, it periodically rewrites ~/.zcode/v2/provider_config.json and clobbers manual model selection. Quit it before configuring the CLI.
  • ZCode records usage locally in ~/.zcode/cli/db/db.sqlite, so Orca can track quota without touching any undocumented billing endpoint.

How to actually use this

Two cases. Don’t mix them up.

You only want quota and history: the desktop app is enough. The GLM Coding Plan link added in v1.4.221 is independent — no CLI needed. Save the key and you get the 5-hour, weekly, and MCP usage rows. The 92% in my screenshot came from that path.

You want ZCode running as an agent inside an Orca pane: install a zcode that has a TUI. The official route is building the command-line distribution from zai-org/ZCode (pnpm build:zcode, which installs to ~/.zcode/runtime and links into ~/.local/bin). There’s also a community zcode-app-cli that extracts the runtime from a pinned desktop release and wraps a TUI around it; people have reported it working on both macOS and Windows in that issue thread.

After installing, check two things: command -v zcode points at the new install, and ~/.zcode/cli/setting.json contains all seven events — SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, Stop.

One last thing

What gets me about this story isn’t “another agent got wired up.” It’s what blocked it for two months.

None of those six PRs were rejected for bad code. They were rejected on the form of the argument: you say it should work, but you can’t show evidence.

Anyone who maintains an open-source project knows this loop — someone files an issue, someone says “works on my machine,” and nobody can prove it will work on yours. What moves things is rarely more enthusiasm. It’s a source tree someone else can check.

On that note, I checked the quota while writing this. Weekly is at 92%. If you’re planning to run anything heavy, wait for next week.


References: