# ZCode

> Run Z.ai's ZCode in NeuroSquad cards — how to install it, what works, and what doesn't yet.

Source: https://docs.neurosquad.ai/en/agents/zcode

**ZCode** is Z.ai's coding agent built around its GLM models. Z.ai published its source under
Apache-2.0; the `zcode` command runs the same agent runtime as the ZCode desktop app, in your
terminal. In NeuroSquad each ZCode agent is a card with the real `zcode` running inside.

Measured on ZCode runtime 0.16.9 (`zcode-app-cli` 3.14.4-32).

## Install

**1. Install the zcode command**

Z.ai publishes no ready-made terminal download, so the `zcode` command comes from npm:

```bash
npm install -g zcode-app-cli@latest
```

`zcode-app-cli` is an unofficial client that ships Z.ai's runtime unchanged. **Settings → Setup**
in NeuroSquad can install it for you. A `zcode` you built from Z.ai's own repository works too.

**2. Set up a provider**

Set up ZCode's providers and default model the way you normally do — cards start from your
providers. A card can also run on [OpenRouter](https://docs.neurosquad.ai/en/providers/openrouter) or on
[your own server](https://docs.neurosquad.ai/en/providers/your-servers) instead.

**3. Add a ZCode card**

Add an agent card and choose **ZCode**. NeuroSquad checks that the `zcode` it finds really is
ZCode — unrelated tools with the same name are not used.

## What works

- **Exact status.** ZCode's own hooks tell the card when it is working, finished, or waiting for
you — with the call it wants to make (`ZCode needs your permission: Bash rm -rf dist`) or the
question it asks. See [Finished / needs your input](https://docs.neurosquad.ai/en/agents/notifications).
- **Arrows.** NeuroSquad's MCP server is in the card's settings, and its own tools never prompt.
ZCode reads a server's tools once, so the card gets every NeuroSquad tool from the start and the
arrows decide at call time. A skill or an installed MCP server needs the card's next start.
- **Canvas mode.** Bash, its background shells and the web tools are removed from what the model
sees, even in dangerous mode. See [Canvas mode](https://docs.neurosquad.ai/en/squads/canvas-mode).
- **Sessions.** After a restart the card continues the same conversation (`zcode --resume`). A
deleted session is replaced by a fresh one.
- **Long sessions.** Context meter, **Compact** (ZCode's `/compact`), the prompt queue, the journal
and hand-off.
- **Usage.** Every request is read from ZCode's own usage ledger — titles, compaction and subagents
included, subagents marked as such — in [Usage & costs](https://docs.neurosquad.ai/en/usage), [Run Stats](https://docs.neurosquad.ai/en/cards/run-stats)
and [Agent Pulse](https://docs.neurosquad.ai/en/cards/agent-pulse).
- **Models and providers.** Pick the model per card; a lead agent can change it with
`agent_set_model`. OpenRouter and your own servers work, with the key kept out of every file.
- **Switching CLIs.** Move the conversation to Claude Code and back.
- **Plugins.** [Memory](https://docs.neurosquad.ai/en/plugins/mem0-memory), [Context7](https://docs.neurosquad.ai/en/plugins/context7-docs),
[Caveman](https://docs.neurosquad.ai/en/plugins/caveman) and [Graphify](https://docs.neurosquad.ai/en/plugins/graphify) reach ZCode's turns; the
[token saver](https://docs.neurosquad.ai/en/plugins/rtk-ai-token-saver) works in dangerous mode.
- **From your phone.** The card works in [remote access](https://docs.neurosquad.ai/en/remote) like any other.

## Dangerous mode

ZCode cards start in dangerous mode with `--mode yolo`. Switching it on or off restarts the card on
the same conversation; turning it off resumes in your usual mode. See
[Dangerous mode](https://docs.neurosquad.ai/en/agents/dangerous-mode).

## Good to know

- **Your `~/.zcode` is only read.** Each card has its own copy of your settings plus NeuroSquad's,
its own session database and, when needed, its own provider file. Keys and tokens are never
written to disk.
- **Stop a turn with Esc.** Ctrl+C on an idle ZCode quits it, so NeuroSquad never sends it — the
budget brake and the phone's key row use Escape.
- **ZCode's project memory is off in a card** unless your own `setting.json` turns it on. Its
background calls are recorded nowhere, so Usage couldn't count them; if you turn it on, those
calls are missing from Usage.
- **Conversations live in the card's database.** A `zcode --resume` in your own terminal finds them
only with `ZCODE_SESSION_DB_PATH` pointing at that file. Deleting a card keeps its database.
- After Escape, ZCode's terminal UI swallows the next key you press.

> ZCode cards run on this computer only — not yet in WSL or SSH workspaces.