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:
| When | What happened |
|---|---|
| July 25 | Issue #10564 asks for ZCode as a first-class agent |
| July 26 | First PR, #10654, opened |
| Mid-August to mid-September | #13965, #14556, #16227, #16228 all opened and all closed unmerged |
| September 20 | One more attempt, #21756 |
| September 20, later that day | Z.ai open-sources zai-org/ZCode under Apache-2.0 |
| September 25 | PR #22464 merges to main |
| September 26, 22:36 UTC | v1.4.214 ships — ZCode becomes a first-class harness |
| September 27 | The 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
zcodeon 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 zaicompleting OAuth is not enough. Foraccount:*providers the CLI additionally requires a Coding Plan API-key credential; with browser auth alone, every turn fails withModel creation failed. You have to run/loginin 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.jsonand 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:
- Orca issue #10564, PRs #22464 and #22730
- Docs: https://www.onorca.dev/docs/agents/supported, https://www.onorca.dev/docs/agents/usage-tracking
- Z.ai’s open-source repo: https://github.com/zai-org/ZCode (Apache-2.0)
