I got ZCode (Z.AI's coding agent) running fully headless from the terminal — cheat sheet

TL;DR: same agent as the desktop app — tools, skills, MCP, plugins — but driven by one-liners you can put in cron. Auth is a one-time browser OAuth; everything else is local config.

Tested on ZCode CLI 0.16.5 · Z.ai Coding Plan (GLM-5.3-Flash) · Linux

---

1. Invocation

The desktop app (/usr/bin/zcode) is Electron; the headless runtime is a Node script shipped with it:

node /opt/ZCode/resources/glm/zcode.cjs [command] [options]

Recommended alias (add to ~/.zshrc):

alias zc='node /opt/ZCode/resources/glm/zcode.cjs'

The working directory is the workspace — cd to your project first (or use --cwd <path>).

---

2. One-shot prompts

# Simplest form
zc -p "explain what this repo does"

# Machine-readable output (great for scripts)
zc -p "count TODO comments and return the number" --json

# Attach files (repeat --attach for multiple)
zc -p "summarize this log" --attach /var/log/app.log

# Run against another directory without cd'ing
zc --cwd ~/projects/api -p "run the tests and fix failures"

--json response shape:

{
  "sessionId": "sess_...",
  "response": "Ok! 🙂",
  "usage": { "totalTokens": 13235, "inputTokens": 13195, "outputTokens": 40 },
  "projection": { "status": "idle", "contextWindow": 1000000 }
}

---

3. Sessions

zc --resume sess_74ff8c6a-... -p "continue that refactor"
zc -c -p "what did we just do?"

Sessions persist per-directory; -c resumes the latest one and keeps prior context.

---

4. Permissions & tool control ⚠️

There is no human to approve prompts in headless mode. -p defaults to --mode yolo (tools run without asking). Constrain unattended runs explicitly:

zc -p "..." --mode plan
zc -p "..." --mode build
zc -p "..." --allowed-tools "Bash(git *) Edit Read"
zc -p "..." --disallowed-tools "Bash(rm *) WebFetch"

Modes: build · edit · plan · yolo (alias: --permission-mode).

---

5. Browser automation

zc -p "open http://localhost:8080 and screenshot the login page" --browser-use headless
# optional: --browser-executable /usr/bin/google-chrome

Browser Use is headed by default — always pass --browser-use headless in cron/scripts.

---

6. What gets loaded (identical to the desktop app)

Resource	Source(s)	Auto-loads?
Skills	~/.zcode/skills/, ~/.agents/skills/, your-repo/.zcode/skills/, your-repo/.agents/skills/, plugin skills	Yes — model triggers by description
MCP servers	~/.zcode/cli/config.json → mcp.servers, your-repo/.zcode/config.json	Yes — trusted, connected at session start
Plugins	enable state in ~/.zcode/cli/config.json → plugins.enabledPlugins	Yes
Hooks	config hooks need "hooks": {"enabled": true}; plugin hooks auto-enable	Yes
Instructions	~/.zcode/AGENTS.md + your-repo/AGENTS.md	Yes
Slash commands	~/.zcode/commands/, your-repo/.zcode/commands/ (dir/name.md → /dir:name)	commands list to inspect

Inspect without spending tokens:

zc skills list      # what the model can trigger
zc plugins list     # enabled/disabled + components
zc commands list    # custom slash commands

---

7. Configuration

User scope: ~/.zcode/cli/config.json · Workspace scope: your-repo/.zcode/config.json

Current model setup (Z.ai Coding Plan, GLM-5.3-Flash for both roles):

{
  "model": {
    "main": "zai/GLM-5.3-Flash",
    "lite": "zai/GLM-5.3-Flash"
  },
  "provider": {
    "zai": {
      "name": "Z.AI Coding Plan",
      "kind": "anthropic",
      "options": { "baseURL": "https://api.z.ai/api/anthropic" }
    }
  }
}

Notes:

• Model refs are "providerId/modelId". lite handles background tasks (session titles, compaction) — pin it too if you want a single model.
• The API key (provider.zai.options.apiKey, format id.secret) is written by zcode login. Keep the file private: chmod 600 ~/.zcode/cli/config.json.
• Model requests are client-signed against the Z.ai endpoint (server-side requirement); a raw OAuth token does not work as a static key.

---

8. Auth

zc login
zc login --no-browser
zc logout

Credentials live in the shared store ~/.zcode/v2/credentials.json — the same file the desktop app uses, so one login covers both.

---

9. Cron / scripted automation

# Nightly code review at 07:00
0 7 * * * cd ~/your-project && node /opt/ZCode/resources/glm/zcode.cjs \
  -p "review yesterday's commits (git log --since=yesterday) and post a summary" \
  --json >> ~/.zcode/automation.log 2>&1

Guardrails for unattended runs: pin the mode/allowlist (§4), check MCP server health first (curl -fsS localhost:3000/sse), and log the sessionId so you can --resume a failed run interactively.

---

10. Programmatic integration

zc app-server

ZCode Protocol server over stdio — drive sessions from your own tooling. Parse --json stdout for sessionId / response / usage; non-zero exit code = run failed.

---

11. Debugging

Symptom	Cause / fix
Model config is missing	~/.zcode/cli/config.json has no model key → add {"main": "zai/GLM-5.3-Flash"}
Model provider zai is missing baseURL	Add provider.zai.options.baseURL (§7)
Model provider is missing an API key: zai	Run zc login
Client signing credential must contain one separator	Key must be id.secret (as written by login) — don't paste a JWT/API key manually
Unknown option '--max-turns'	Listed in help but not wired in 0.16.5 — omit it
Wrong model seems to answer	Check actual wire traffic: ~/.zcode/cli/rollout/model-io-sess_X.jsonl → "modelId"
MCP tools missing	Is the hub process up? curl localhost:3000/sse
Need verbose diagnostics	Add --verbose (stderr stack traces)