0.3.0

zcode is a command-line executor for orchestrator agents. Claude Code, Codex, or any agent with a shell hands it a task contract. zcode implements the task with GLM-5.3-Flash, runs your checks itself, and returns a handback that lists the changed files, the check results, and anything it could not verify.

The orchestrator keeps product decisions, design direction, and coordination. zcode works only inside the scope it is given.

 

Quick start

npm install -g @0xgeorgemathew/zcode
echo "$ZAI_API_KEY" | zcode login    # stores your Z.AI key with mode 600; zcode never prints it
zcode doctor                         # checks the engine, isolation and key
zcode skills install                 # optional: teach Claude Code and Codex to delegate to zcode

zcode task --check "npm test" "Fix the off-by-one in src/paginate.ts"

The CLI needs node 20 or later. The engine child runs best on node 26. zcode also needs the ZCode engine, which today ships inside the ZCode desktop app; zcode finds it automatically.

The package ships skills that teach Claude Code and Codex how to delegate to zcode. Install them with one command:

zcode skills install          # both; or: zcode skills install claude | codex
zcode skills                  # show what is installed and where
zcode skills uninstall        # remove them

The Claude Code skill goes to ~/.claude/skills/zcode and the Codex skill to ${CODEX_HOME:-~/.codex}/skills/zcode. The package runs no install scripts. Details are in skills/.

 

Models and effort

Every command runs on GLM-5.3-Flash (it sees images) at effort max unless you pass a flag. --model glm-5.3 is an explicit override: GLM-5.3 cannot see images (zcode doctor shows images / no images per model). Plan sessions, units, resume, run and agent all default to Flash too, and the visual verifier always uses an image-capable model. Subagent profiles copied from your desktop that pin a GLM-5.3 id are rewritten in the session's copy to the session's model.

zcode task "..."                                   # GLM-5.3-Flash, effort max
zcode task --effort high "..."                     # Flash with less reasoning
zcode task --model glm-5.3 "..."                   # GLM-5.3, effort max
zcode task --model glm-5.3 --effort high "..."     # GLM-5.3, effort high

A task contract can set "model" and "effort". Flags override the contract. A resumed session keeps its original model and effort unless you pass the flags again.

 

Hand off a task

zcode task --cwd ./site --id page-1 \
  --owns src/pages/pricing/ \
  --check "npm run build" --check "npm test -- pricing" \
  --accept "Three plan cards, the middle one highlighted" \
  --context @design/pricing.md \
  "Implement the pricing page from the supplied design notes"

zcode turns this into an execution contract and runs a fresh engine session in yolo mode, with --cwd as the blast radius. The model may split the work across subagents. When it finishes, zcode runs the checks itself. If a check fails, zcode feeds the failure output back for a bounded number of repair turns (--max-repairs, default 2), then reports:

✓ completed  page-1  142.3s
  Pricing page with three plan cards; middle card highlighted per design notes.
changed  3 files
  A src/pages/pricing/index.tsx
  A src/pages/pricing/PlanCard.tsx
  M src/pages/pricing/styles.css
checks   2/2 passed  ·  1 repair turn
  ✓ npm run build
  ✓ npm test -- pricing
not verified
  - prose acceptance criteria are confirmed only by the executor's own report

That block is the format of the summary printed to stdout. The live feed (session header, phases, tools, subagents, check results) goes to stderr. With --json you get the compact brief as one machine-readable result line (see Machine interface).

For small work, the objective alone is enough: zcode task "Fix the typo in the README heading".

The contract

Flags cover the common fields. For richer handoffs, pass --task contract.json, --task brief.md, or --task - to read stdin. Only objective is required; unknown keys are rejected so a typo never silently drops a requirement.

{
  "objective": "Implement page 2 (Team) per the design spec",
  "scope": ["Team page route and its components"],
  "constraints": ["No new dependencies", "Keep existing routing untouched"],
  "decisions": ["Grid of 3 columns ≥1024px, 1 column below", "Use tokens from src/theme.ts only"],
  "acceptance": ["Every member card shows name, role, avatar"],
  "checks": ["npm run build", "npm test -- team"],
  "files": ["src/theme.ts", "src/pages/home/index.tsx"],
  "references": ["design/team.png described in design/team.md"],
  "context": ["Copy lives in content/team.json"],
  "owns": ["src/pages/team/**", "content/team.json"],
  "limits": { "timeoutMs": 7200000, "maxRepairs": 2, "checkTimeoutMs": 300000 },
  "effort": "high"
}

decisions (flags --decision "…", repeatable, and --decisions @file; design is an alias) are presented to the model as binding decisions it must implement, not revisit. @file entries inside contract decisions/context lists are inlined (relative to the contract file, then to --cwd; the error names both paths). If something user-visible or behavioural is left open, the executor does not guess: when it blocks the work it reports blocked with a structured question {"q", "options": [...], "recommend"} (plain strings still work); when it does not block, it takes the most conservative choice and lists it in the handback decisions: [{what, why}], which the brief carries so the orchestrator can overrule it.

A file passed with --file and also inlined with --context @file reaches the executor once (as context); identical context and acceptance entries are deduped.

Preflight. --preflight runs a read-only turn over the same contract: the executor lists every open question it would otherwise guess and makes no edits; zcode runs no checks. The result is blocked with questions, or completed with summary no open questions; any changed file fails it (preflight_wrote). The session is recorded as a preflight; zcode resume <id> "<answers>" then switches it to execution: the answers plus the full task protocol go to the executor, and checks and visual verification run as usual.

Units. --unit "name: objective [owns a,b]" (repeatable; contract units: [{name, objective, owns?}]) makes the executor dispatch each unit to its own subagent inside this one session, in parallel where independent, then integrate and verify the whole. Unit owns must lie within the session's --owns and be disjoint from each other (exit 2 otherwise). The handback units: [{name, status, note}] is listed under notVerified as executor claims; zcode's checks still verify the integrated result.

Visual verification. --visual "criterion" (repeatable; contract visual), --viewport WxH (repeatable, default 390x844 and 1440x900; contract viewports) and --serve "cmd" (contract serve; must honour $ZCODE_PORT, default: the executor reads package.json) make zcode, not the implementer, judge the rendered result. After the implementer's turn (and once the checks pass) zcode opens a fresh engine session on the first image-capable model (GLM-5.3-Flash, effort high, same workspace and session environment) that did not build the result. It serves the app on $ZCODE_PORT, waits for fonts and animations, captures viewport and full-page screenshots into $ZCODE_OUT/verify/<round>/ at each viewport, looks at them, makes no edits, and answers with a zcode-visual block: [{criterion, viewport, met, seen, note, shot}], quoting the text it can read (seen). It also always judges one built-in criterion: all text the page means to show is readable after animations finish (not clipped, hidden, transparent, off-screen or overlapped). Those entries are the result's visual; the implementer's own claims are kept only as executorVisual in the full record. Unmet criteria spend the repair budget like failing checks (the repair turn goes to the implementer with the verifier's seen, note and shot paths; then checks and a new verifier round run). A verifier that fails or returns no parsable block is retried once; still nothing gives met: null, status partial and the issue visual not verified. Still unmet after the budget: partial with visual criteria unmet: …. An implementer on a model that cannot see images is told so and to self-check visibility in the DOM instead. Files the verifier changes outside .zcode/ are reported as the issue verifier edited files: …. Verifier turns count in usage. Without --visual nothing changes.

Status: what a result means

A model claiming success is never enough on its own. A subagent ending success only means it returned. The handback block the model writes is reported as handback (a claim), and the status is derived from what zcode observed. notVerified lists anything zcode could not check itself.

 

Sessions

Every invocation gets a session: --id page-1, or a generated zc-xxxxxxxx. Each session has its own engine HOME (~/.zcode-cli/sessions/<id>/home), so conversation state, engine database, MCP servers, and skills never leak between sessions. An existing id is never re-run, so retrying a start you lost track of fails fast instead of doing the work twice. Use status to check on it, or resume to continue it.

zcode task --detach --id page-1 --owns src/pages/home/ --check "npm run build" "Build page 1"
zcode task --detach --id page-2 --owns src/pages/team/ --check "npm run build" "Build page 2"
zcode status                 # all sessions: id, state/status, kind, updated, label
zcode status page-1 --json   # one session: state, phase, activity, recent events, result
zcode wait page-1 page-2     # block until both finish; print each handback
zcode wait page-1 page-2 --any   # return as soon as the first one finishes
zcode result page-1          # a finished session's handback, without waiting
zcode resume page-2 "Use the 2-column variant below 1024px."   # answer / follow up / retry
zcode cancel page-1          # stop the turn and any running check; recorded as cancelled

• Lifecycle. A session is queued, then running, then finished with a status. If the process that owned a running session dies, the session shows as interrupted, which can be resumed.
• Resume sends your message into the same engine conversation. For task sessions, the model is told that earlier work is already applied to the workspace, and zcode re-runs the checks and repairs and produces a fresh handback. A resume with no message (task sessions) means "continue from where you stopped".
• Never automatically re-sent. zcode retries only engine start-up, which happens before anything reaches the model. A prompt that was delivered is never re-sent automatically. Continuing is always an explicit resume.
• Detached sessions write their NDJSON to ~/.zcode-cli/sessions/<id>/stdout.ndjson and diagnostics to stderr.log. The handback lands in result.json. You never need to read these files: status and wait print everything.

Concurrency and ownership

--owns declares what a session may change: a path owns its subtree, and globs are supported. Patterns are relative to --cwd. A session without --owns owns the whole workspace, which is right for a one-off task in its own checkout.

• Starting a session whose ownership overlaps a running session in the same workspace is refused with exit 7, unless --allow-overlap is passed. The workspace is the git toplevel, so sibling directories of one repo count as one workspace. Disjoint owners (src/pages/home/ vs src/pages/team/) run side by side.
• After the work, zcode diffs the workspace and reports each changed file. Changes outside the session's ownership are listed in scopeViolations, and for task sessions they make the result partial. Files that fall in a concurrent session's ownership are attributed to that session, not counted against this one.
• For overlapping or risky parallel work, give each session its own git worktree via --cwd.
• ZAI_CODE_MAX_ACTIVE (default 8) is a soft machine-wide cap. Sessions beyond it wait in queued.
• Session environment. Every session's executor and every check run with ZCODE_SESSION_ID, ZCODE_PORT (a free TCP port from 41000-48999, reserved per session and unique among live sessions, also recorded in the session), ZCODE_OUT (<cwd>/.zcode/out/<id>, created) and ZCODE_TMP (a per-session scratch dir). The task prompt tells the executor to use them for dev and preview servers, build output dirs and test artifacts, so parallel sessions cannot collide on a port or a dist/. Files under .zcode/ never count as changes or scope violations; add .zcode/ to the .gitignore of repos you run zcode in.
• --touch <path|glob> (repeatable; contract key touch) allows minimal edits outside --owns without declaring ownership. Touched files are listed in touched and are not scope violations, so one stray line in a shared stylesheet no longer blocks a session. Starting is refused with exit 7 if a running session owns a matching path; a touch reserves nothing, so it never blocks another session's --owns.

Plans: several sessions with dependencies

zcode plan runs a set of task sessions as one unit, in dependency order, and returns a single summary.

{ "decisions": ["@decisions.md"], "context": ["@brief.md"], "effort": "high",
  "sessions": [
    { "id": "tokens", "objective": "Design tokens", "owns": ["src/tokens/**"], "checks": ["npm run lint"] },
    { "id": "home",   "objective": "Home page", "after": ["tokens"], "owns": ["src/home/**"] },
    { "id": "team",   "objective": "Team page", "after": ["tokens"], "owns": ["src/team/**"] }
  ] }

Optional top-level keys: cwd (relative to the plan file), decisions, context, files (prepended to every session; @file entries are read relative to the plan file, then against the plan's cwd), model, effort, limits (timeoutMs, maxRepairs, checkTimeoutMs: the default for every session; a session's own limits override per key). Each session has an id (its zcode session id), optional after (ids), optional label (the session label becomes plan:<name> <label>) and any task contract keys. In plan run --preflight, a session with after is told which upstream sessions have not run yet and to assume they deliver their objectives.

zcode plan check plan.json              # validate: exit 2, one line per problem
zcode plan run plan.json --preflight    # read-only questions per session (<id>.pre); exit 10 if any
zcode plan run plan.json --detach       # supervise in the background
zcode plan wait plan   --json --timeout-ms 600000   # one line; exit 124 on timeout
zcode plan status plan                  # one line per session
zcode plan resume plan "answers…"       # resume failed/partial/blocked sessions, relaunch skipped ones

A session starts once everything it is after has completed; sessions that can run together must own disjoint paths (plan check enforces it). A session that ends without completing marks its downstream skipped while the others continue. The summary is {"type":"plan","name","status","sessions":[{"id","status"}],"briefs":[…]} with a brief for each finished session that did not complete. Exit codes: 0 completed, 10 blocked, 8 partial or failed, 124 timeout. Plan status is derived from the sessions, so it stays accurate even if the supervisor process dies; plan resume restarts it. The plan name is the file's basename (--id overrides); ids that already exist as sessions are refused, so re-run through plan resume.

 

One-shot turns and subagent dispatch

zcode with a prompt (or zcode run) is a plain turn. The answer streams to stdout, and thinking is mirrored to stderr as │ lines.

zcode "What is 17*23? Reply with only the number."
zcode --effort high "Draft a commit message for the staged diff"
echo "$PROMPT" | zcode

zcode agent "<instructions>" forces a dispatch through the engine's Agent tool. It is verified from session/subagents: exit 6 if no subagent ran or any ended in a status other than success. --profile picks the subagent profile (default general-purpose).

Inside zcode task, subagents are optional. The executor decides when to use them, gives each a bounded scope and file ownership, and must verify the integrated result.

 

Machine interface

--json: stdout carries NDJSON events, then exactly one final {"type":"result",…} line. With --quiet, the result line is the only output. For task sessions, text/reasoning deltas are left out of the events unless you pass --stream, so an orchestrator reading the output pays only for lifecycle events.

The final line is the compact brief (zcode.brief/1), sized for an orchestrator that spends tokens on decisions. Keys with empty values are omitted:

{"type":"result","schema":"zcode.brief/1","status":"failed","ok":false,"id":"page-1","label":"home",
 "summary":"…(≤600 chars)…","files":["src/pages/home/index.tsx"],
 "checks":[{"command":"npm run lint","ok":true},{"command":"npm test","ok":false,"exitCode":1,"tail":"…last 1500 chars…"}],
 "questions":[],"issues":["…"],"unresolved":[],"scopeViolations":[],"error":{"kind":"checks_failed"},
 "result":"/…/sessions/page-1/result.json"}

The brief lists unmet visual criteria only (visualMet: "M/N" counts them all), at most 6 decisions (decisionsMore) and 40 files (filesMore, concurrent sessions' files excluded). run and agent briefs also carry response, because the text answer is the product there. Only failing checks are listed (checksPassed: N counts the passing ones); a failing check carries exitCode, timedOut and the last 1500 characters of its output as tail. result is the path to the full record: result.json on disk is always the full zcode.result/1 record, and --full prints that same record instead of the brief (on task/run/agent/resume/wait/result):

{"type":"result","schema":"zcode.result/1","ok":true,"status":"completed","id":"page-1","kind":"task",
 "summary":"…","response":"…executor report…","issues":[],"questions":[],"unresolved":[],"notVerified":[],
 "changes":{"tracking":"git","files":[{"path":"src/pages/home/index.tsx","change":"added","owned":true}]},
 "scopeViolations":[],"checks":[{"command":"npm run build","ok":true,"exitCode":0,"timedOut":false,"durationMs":8123,"output":"…tail…"}],
 "checksPassed":true,"repairs":0,"handback":{"status":"done","summary":"…","changes":[],"checks":[],"criteria":[],"unresolved":[],"questions":[],"notes":""},
 "subagents":[{"agentId":"agent_…","profileId":"general-purpose","status":"success","summary":"…","durationMs":59765}],
 "error":null,"cwd":"/abs/site","workspaceRoot":"/abs/site","owns":["src/pages/home/"],"sessionId":"sess_…","resumed":false,"turns":1,
 "model":"GLM-5.3-Flash","effort":"max","mode":"yolo","usage":{"inputTokens":19608,"outputTokens":3120},
 "toolCalls":14,"durationMs":142301,"files":{"session":"…/sessions/page-1","result":"…/result.json","events":"…/events.ndjson"}}

model and effort are engine-reported (from the engine's model_request_started event), not echoes. sessionId is the engine's session id; id is the zcode session id you pass to status, wait, result, resume, and cancel. A run that fails still ends with a parseable result line.

zcode status <id> --json returns {"type":"status", state, status, phase, pid, live, activity, recent:[…], result?}. zcode wait --json prints one brief per session as each finishes (--full: full records; --any: stop at the first). When --timeout-ms elapses first it prints exactly one line per session still running, {"type":"pending","id","state","phase","elapsedMs"} (human mode: <id> <state> <phase> 12m), and exits 124. zcode watch [<id>… | --plan <name>] [--stall-min 8] is a live view for humans (no model tokens): one line per session, id state phase[ n/m] elapsed last: <tool> <age> ago req <n> sub <running>, with STALLED? appended when a running session has had no engine event for --stall-min minutes (default 8). On a TTY it redraws every 2 s; piped, it prints a line when a session changes; it exits 0 when every watched session has finished (no arguments: live sessions and those finished in the last 10 minutes). status <id> (human and --json) gains idleMs and stalled: true for running sessions by the same rule, and wait / plan wait pending lines carry idleMs (stalled: true when so). Nothing is done automatically. zcode result <id> [--json] [--full] prints a finished session's handback without waiting (exit 7 if it is still running). zcode status without an id is one line for each of the 15 most recent sessions plus … N more (zcode status --all). zcode <command> --help prints only that command's usage (under 2000 bytes); bare zcode --help is the full reference. Usage errors are always a single line (zcode: unknown flag (did you mean …?) for a mistyped option), never the help text.

 

Options

Only glm-5.3 and glm-5.3-flash are accepted; anything else exits 2 before any spawn. The effort levels each model accepts are read from the engine's builtin provider config (zcode doctor --json lists them as models; a built-in table is the fallback). An unsupported model and effort pair, whether from --effort, the task contract, or a resumed session's stored setting, exits 2 with one line naming the supported values, before any engine is spawned.

Exit codes

 

Under the hood

Key handling. The key comes from the ZAI_API_KEY env var, or from zcode login, which stores it at ~/.zcode-cli/credentials.json (mode 600). It is never printed or logged. Engine messages and check output are scrubbed before they are stored or shown. The only files the key ever lands in are each session's scratch provider config, which the engine requires to register the provider.

Isolation. This package's state lives under ~/.zcode-cli, never under ~/.zcode, which belongs to the desktop app. Each session's engine runs with HOME pointed at its own scratch directory. On every invocation zcode rewrites the scratch config from your live desktop config: provider rule with your key, agent profiles, skills, MCP servers. It never touches the engine's database there, so sessions stay resumable. The desktop's OAuth credentials.json is never copied, and the live ~/.zcode is never written. The engine's ~30 MB plugin cache is shared between sessions through a symlink.

Yolo mode. Tool side effects are auto-approved, matching the engine's own headless default; --cwd is the blast radius. If a headless turn requests interactive input, the result is reported as blocked instead of hanging. The executor contract forbids commits, pushes, deploys, and other external side effects unless the task explicitly asks for them.

Environment. ZAI_CODE_HOME (state root), ZAI_CODE_ENGINE (engine bundle), ZAI_CODE_NODE (engine interpreter), ZAI_CODE_BUILTIN_PROVIDER_CONFIG, ZAI_CODE_LIVE_DIR (desktop config dir, default ~/.zcode), ZAI_CODE_MAX_ACTIVE, NO_COLOR.

 

Development

Zero dependencies, plain CommonJS, no build step.

npm test              # unit suite: in-process, scripted fake engine, no CLI spawn, no API calls
npm run test:live     # functional suite: spawns the CLI against the real engine and GLM API
npm run accept:flash  # black-box acceptance runs (real API)
npm run accept:subagent
npm run accept:53

Live tests load the key from the repo .env, which is never committed or shipped. The design record and the wire-protocol facts pinned live are in DESIGN.md (§17 covers the 0.4 executor redesign) and docs/BUILD-REPORT.md.

License

MIT. Source and issues: github.com/0xgeorgemathew/zcode.