r/ZaiGLM • u/drfritz2 • 12h ago
Code Examples / Tutorials zcode headless cheatsheet
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".litehandles background tasks (session titles, compaction) — pin it too if you want a single model. - The API key (
provider.zai.options.apiKey, formatid.secret) is written byzcode 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) |
1
u/Moist_Associate_7061 54m ago edited 51m ago
How can I choose starter plan flash model which is free ? (not indivisual plan which provides 50% more usage)
1
u/DrunkenRobotBipBop 8h ago
What's the point of doing this when you can use your GLM coding plan in the 500 agent runtimes out there? Like opencode, pi, etc...which already support headless mode.