Zaru CLI｜终端内运行、需先授权再执行的 AI 编程助手（pre-alpha，源码构建）

access：来源确认 · git clone https://github.com/100monkeys-ai/zaru-cli.git cd zaru-cli cargo install --path crates/zaru-cli --locked

project_type：来源确认 · Zaru is an AI assistant that works in your terminal. You give it a task, it asks a language model, and it runs the tools the model asks for

# Zaru

Zaru is an AI assistant that works in your terminal. You give it a task, it asks a language model, and it runs the tools the model asks for: it reads and edits files, runs commands and fetches web pages, asking your permission first. Every step is written to a plain-text transcript you can read with `cat`.

This repository is the `zaru` command-line program. It is pre-alpha: there are no releases and no packages, you build it from source, and commands, files and settings can change without notice.

## Requirements

- Linux. The program is built and tested on Linux only. It uses Unix-only APIs, so it does not build on Windows. macOS is not tested.
- Rust 1.98.1. The version is pinned in [`rust-toolchain.toml`](rust-toolchain.toml), and `rustup` installs it for you on the first build.
- A C compiler (`cc`). Some dependencies compile C code.
- Network access to crates.io for the first build.
- A model to talk to: a Google Gemini API key, an [Ollama](https://ollama.com) server, or any server with an OpenAI-compatible chat completions API.

## Build and install

```sh
git clone https://github.com/100monkeys-ai/zaru-cli.git
cd zaru-cli
cargo install --path crates/zaru-cli --locked
```

This builds the `zaru` binary and copies it to `~/.cargo/bin`; `zaru --version` checks that it runs. To build without installing, run `cargo build --locked`; the binary is then `target/debug/zaru`.

## Quick start

### 1. Choose a model

Zaru has no default model. You name one in `~/.zaru/config.toml`, which you create yourself.

**Gemini.** Store your API key. It is read from standard input: paste it, press Enter, then press Ctrl-D.

```console
$ zaru providers keys add gemini
stored a `gemini` key under the alias `provider.gemini`.
  the value is sealed and is not printed by any command.
```

Then name the model in `~/.zaru/config.toml`:

```toml
[model]
default = "gemini-3.6-flash"
```

Stored keys are encrypted with a key kept in your operating system's keyring. If the machine has no keyring (a server, WSL, a container) and a task needs a stored key, `zaru` tells you so and stops. Set `ZARU_CREDENTIAL_KEY` to 64 lower-case hexadecimal characters in your shell profile, for example the output of `openssl rand -hex 32`, and keep that value: without it, the keys you stored cannot be read again. A task that needs no stored key, such as one for Ollama, goes on without it and says that the stored keys could not be read.

**Ollama.** No key is needed. Start the server, then write `~/.zaru/config.toml`:

```toml
[model]
default = "llama3.2"

[provider.default]
kind = "ollama"
```

Zaru connects to `http://localhost:11434`. Set `provider.ollama.endpoint` if your server is elsewhere.

**An OpenAI-compatible server.** Give the base URL (Zaru adds `/chat/completions` to it). If the server's `/models` list does not give the model's context window, give it in tokens too:

```toml
[model]
default = "your-model-name"

[provider.default]
kind = "openai-compatible"

[provider.openai_compatible]
endpoint = "http://localhost:8080/v1"
context_tokens = 32768
```

If the server needs a key, store it with `zaru providers keys add openai-compatible`.

### 2. Run a task

Run `zaru` with the task in quotes, from the directory you want it to work in:

```console
$ zaru "read src/main.rs and tell me what it does"
Zaru is not a sandbox. Tool calls run on your machine with your permissions. A permission prompt asks before a call runs; it does not limit what an allowed call can do.

fs.read /home/you/project/src/main.rs — permitted
  read src/main.rs · lines 1 to 42 of 42

<the model's answer>

tokens: 120 prompt + 7 completion = 127, counted by the provider

no validators are declared, so the iteration loop cannot run · declare one in `./zaru.toml`
```

It prints a warning that it is not a sandbox (see [Safety](#safety)), each tool call the model made with what it did (see [What a tool call shows](#what-a-tool-call-shows)), the model's answer, the tokens the task used as the provider counted them, and a note about validators (see [Validators](#validators-and-the-iteration-loop)). These lines use plain ASCII marks, so they read the same through a pipe.

When the model wants to write a file or run a command, Zaru asks you first. If there is no terminal to ask (for example, when `zaru` runs in a script), the call is refused and the model is told so.

### 3. Read the transcript

Each task creates a session: a directory under `~/.zaru/sessions/` named by a session ID.

```sh
zaru sessions list
cat ~/.zaru/sessions/<id>/transcript.jsonl
```

The transcript has one JSON object per line: your task, each model reply with the tool calls it asked for and their arguments, each tool call and whether it was allowed, what each call returned exactly as the model was given it, what the screen showed of each call's result, and the answer. Stored keys and tokens are replaced with a marker before a model reply or a tool result is written.

## Using Zaru

### Interactive sessions

Run `zaru` with no arguments in a terminal to open a session. Type a task and press Enter; each task you type continues the same conversation, and the model is sent every earlier task, reply, tool call and tool result in it. Type `/help` to list commands. Type `/exit`, or press Ctrl-C when nothing is running and the prompt is empty, to leave. Ctrl-C while a task runs, or at a permission prompt, stops the task and keeps the session open.

`zaru --continue` reopens the most recent session started in the current directory, and `zaru --resume <id>` reopens the session with that ID. The conversation is rebuilt from the transcript, so the model is sent the same conversation it had before. A session recorded before tool results were kept reopens with your tasks and the answers, and says once that the earlier tool results were not recorded. When the output is not a terminal, both print the session's transcript and exit instead. The line at the top of the screen shows the runtime tier, the model, the permission mode, how much of the model's context window is used, the tokens the provider counted for the last request, and the session ID. The context figure is an estimate and is marked `~`, for example `~2.1k/4.0k`: Zaru has no tokenizer, so it divides a request's bytes by a bytes-per-token ratio. It starts at 3 bytes a token and, after each answer, uses what the provider counted. The provider's own count is marked `counted`.

**When the conversation gets long.** At three quarters of the window Zaru summarises the oldest turns and says so (`◈ compacted …`); the whole history stays in the transcript. The last eighth of the window is kept for the model's answer, so a request is sent only when its estimate fits in the other seven eighths. If one request cannot fit, for example after a tool returned a very large result, Zaru does not send it: it says how large the request is, which tool result is largest, and what to do. For Ollama, every request also tells the server not to cut the prompt (`"truncate": false`).

**Selecting text.** A session takes over the mouse so that the scroll wheel scrolls the transcript. To select text, hold Shift while you drag (this works in most terminals, including Windows Terminal and VS Code). To give the mouse back to your terminal instead, set `terminal.mouse = false` in `~/.zaru/config.toml`; the scroll wheel then no longer scrolls the transcript.

### What a tool call shows

Under each tool call the screen shows what the call did, as the model was given it:

- **A command**: its exit code and how many lines it printed on standard output and on standard error, then its last 7 lines. Lines from standard output start with `out` and lines from standard error with `err`. A command that printed nothing says so. The output is shown when the command ends, not while it runs.
- **An edit or a write**: the lines it changed, with each line's number. A removed line is marked `-` and an added line `+`, with 2 unchanged lines on each side of a change, and at most 7 rows. A new file shows its first 5 lines and how long it is.
- **A read, a listing, a search or a fetch**: one line saying what came back: which lines of which file, how many entries, how many lines matched in how many files, or the page's status, size and title.

The marks are characters, so they do not depend on colour. A long line is cut at the edge of the screen. When a block leaves lines out, or cuts a long line, all of it is kept in a file in the session's folder, such as `~/.zaru/sessions/<id>/shown-0001.txt`, and the block's last or first line gives the file's path. A stored key is shown as its marker, never its value. Output that would move the cursor, clear the screen or change the terminal's title is shown written out, for example `\u{1b}[2J`, and the terminal does not act on it. Nothing shown here is sent to the model.

### Permission prompts and modes

Before a tool call that needs permission, Zaru shows what the call will do (for a file write, the file and its new contents) and asks `[y/N/a · a allows this exact line for this session · esc says no to this call · ctrl-c stops the turn]`. `y` allows the call once. `a` allows the same call for the rest of the session. `N`, Enter or Esc says no to this call: the model is told you said no, and the task goes on. Ctrl-C stops the whole task: the call does not run, no other call runs, and the session stays open for your next task. The file, command or web address the prompt asks about is always on its first lines. On a small terminal a long path is shortened in the middle so its start and the file's name both show, a long command shows the program and says how many arguments it leaves out, and a long preview shows its first lines and says how many it leaves out. Before fetching a web page, Zaru shows the whole URL and also offers `h`, which allows every URL on that host for the rest of the session.

The permission mode decides what needs asking. Set it with `tools.mode` in `~/.zaru/config.toml`, the `ZARU_TOOLS_MODE` environment variable, or `--mode` on the command line:

| Mode | What it asks about |
| --- | --- |
| `ask` (default) | Every file write, file edit, command, web page fetch and Carbon Forge call, and anything outside the working directory. Reading, listing and searching files inside it do not ask. |
| `allow` | Nothing on your allowlist; everything else. |
| `yolo` | Nothing. Every call the model makes runs. |

The allowlist is `tools.allowlist` in `~/.zaru/config.toml`: a list of the exact lines the prompt shows, for example `"cmd.run cargo test"`. For `web.fetch` an entry may also name a host with no `http://` or `https://`, for example `"web.fetch docs.rs"`, which allows every URL on exactly that host. A project's own files cannot set the mode or the allowlist.

### Configuration

Zaru reads settings from these places. A later one overrides an earlier one:

1. built-in defaults
2. `~/.zaru/config.toml`, your settings
3. `./zaru.toml`, the project's settings (only `[project]`, `[runtime]` and `[[validator]]`)
4. environment variables: the key in upper case with `ZARU_` in front, for example `ZARU_MODEL_DEFAULT`
5. command-line flags

`zaru config explain <key>` shows the value from every place and marks the one in effect. The keys most people need:

| Key | Meaning |
| --- | --- |
| `model.default` | The model to use. `--model` sets it for one run. |
| `provider.default.kind` | `gemini`, `ollama` or `openai-compatible`. |
| `provider.ollama.endpoint`, `provider.openai_compatible.endpoint` | Where the model server listens. |
| `provider.<kind>.context_tokens` | The model's context window, in tokens. See [Context window](#context-window). |
| `tools.mode`, `tools.allowlist` | See [Permission prompts and modes](#permission-prompts-and-modes). |
| `runtime.max_iterations` | How many attempts the validator loop makes. |
| `runtime.max_tool_exchanges` | The most model replies one task may have: 50 unless you set it. At the limit the task stops, the session stays open, and typing `continue` goes on. A project may lower it and not raise it. |
| `terminal.mouse` | `false` gives mouse selection back to the terminal. |

### Context window

When a session opens, Zaru asks the provider how large the model's context window is: Gemini's model description, Ollama's `show`, or the `/models` list of an OpenAI-compatible server. If the provider does not say, Zaru uses `provider.<kind>.context_tokens` from your configuration, and if that is not set, its own default: 1,048,576 for Gemini and 4,096 for Ollama. An OpenAI-compatible server has no default, so if it does not say, you must set the key. Your setting can lower what the provider says and never raises it. For Ollama the model's own figure only lowers the window, because Ollama serves the window Zaru asks for (`num_ctx`), and asking for the model's full length can take gigabytes of memory; set `provider.ollama.context_tokens` to use more. `zaru models` shows the window and which of the three it came from.

### Validators and the iteration loop

A validator is a command in `./zaru.toml` that checks the model's work, such as a build or a test run. When a project declares validators, a task runs in a loop: the model makes a change, the validators run, and if any fails, its output goes back to the model for another attempt. The loop stops when every validator passes or when it reaches `runtime.max_iterations` attempts, which is one at the `bare` tier unless you set it. The screen shows each attempt's tool calls and what they did, as it does for any task. The next task you type is sent each attempt's tool calls and their results, as it is sent a task's; the harness's requests for another attempt are not sent again.

`zaru init` writes an example `./zaru.toml` to edit. A small one:

```toml
[[validator]]
name = "test"
run = "cargo test"
expect = "exit-zero"
```

`expect` can be `"exit-zero"`, `{ exit-code = 2 }`, `{ matches = "<regex>" }` or `{ json_schema = "<file>" }`. If the validators never all pass, `zaru` exits with code 1.

Validators are commands, so none runs until you approve them. Before the first one runs in a project, Zaru shows every validator's name and command and asks. Your answer is kept in `~/.zaru/approved-validators.jsonl`, for that directory and that exact set of commands. If `zaru.toml` changes them, Zaru asks again and shows what changed. When there is no terminal to ask on, the task is refused: run `zaru validators approve` in the project's directory to see the commands and approve them, and `zaru validators list` to see what you have approved. The permission mode does not change this, `yolo` included.

### Carbon Forge

Carbon Forge is 100monkeys' notes service. `zaru notes tokens add <alias> <host>` stores an access token for it, read from standard input. When a session opens with a stored token, Zaru suggests matching page and atom names from your notes as you type. The model can call a Carbon Forge instance's tools only if you list them under `notes.<alias>.agent_tools` in `~/.zaru/config.toml`.

## Command reference

`zaru "<task>"` runs one task. `zaru` with no arguments opens a session in a terminal and prints help otherwise.

| Command | What it does |
| --- | --- |
| `zaru runtime` | Show the runtime tier and what the other tiers would change. |
| `zaru models` | Show each model alias (`default`, `fast`, `smart`, `cheap`, `local`) and the model it resolves to, and the context window a session would use and where it comes from. |
| `zaru config explain <key>` | Show one setting's value at every level, marking the one in effect. |
| `zaru init` | Write an example `./zaru.toml`, if there is none. |
| `zaru providers keys` | List the provider keys stored on this machine. |
| `zaru providers keys add <kind>` | Store a provider key, read from standard input. |
| `zaru providers keys rm <kind>` | Delete a stored provider key. |
| `zaru validators approve` | Show the validators in `./zaru.toml` and ask to approve them. |
| `zaru validators list` | List every project whose validators you approved, and their commands. |
| `zaru sessions list` | List the sessions on this machine. |
| `zaru sessions rm <id>` | Delete a session's directory. |
| `zaru notes tokens` | List the stored Carbon Forge tokens. |
| `zaru notes tokens add <alias> <host>` | Store a Carbon Forge token, read from standard input. |
| `zaru notes tokens describe <alias> <text>` | Add a description to a stored token. |
| `zaru notes tokens rm <alias>` | Delete a stored token. |
| `zaru notes use <alias>` | Choose which token the session's suggestions use. |
| `zaru learned` | Not built yet; says there is nothing to show. |
| `zaru inbox` | Not built yet; says there is nothing to show. |
| `zaru help` | Print the help text. |

| Flag | What it does |
| --- | --- |
| `--model <identifier>` | Use this model for one run. A model alias such as `cheap` means the model it resolves to; anything else is taken as the model's identifier. |
| `--mode <mode>` | Use this permission mode for one run: `ask`, `allow` or `yolo`. |
| `--runtime <tier>` | Use this runtime tier for one run. |
| `--resume <id>` | Reopen a session. |
| `--continue` | Reopen the most recent session started in this directory. |
| `--help` | Print the help text. |
| `--version` | Print the version and the libraries it is built from. |

## Safety

Zaru acts on your machine with your user account's permissions. It is not a sandbox.

- **What the model can do.** It has seven built-in tools: `fs.read`, `fs.list`, `fs.search`, `fs.write`, `fs.edit`, `cmd.run` and `web.fetch`. `fs.read` returns at most 500 numbered lines at a time, fewer when the lines are long, and says how many lines the file has and where to start to read on; it refuses a binary file or one that is not UTF-8, naming its size. `fs.edit` changes text that occurs exactly once, or every occurrence when asked; it keeps the file's line endings and final newline, and when the text is not found it shows the nearest lines. `fs.write` says whether it created a file or replaced one, and how large the old one was. `fs.search` looks for plain text in the files under a folder, and in their names. A needle with no capital letters matches any case; a call can ask for exact case, whole words or one file type. It skips what `.gitignore` and `.ignore` files name, the folders `.git`, `target`, `node_modules`, `vendor`, `dist`, `build`, `__pycache__`, `.venv` and `venv`, and lock files, unless the call asks to include them. It shows at most 40 matching lines, grouped by file and ranked: definitions first, then source, then tests, then generated files. It says how many more lines there are, how to narrow the search, how many files it read and what it did not search. A needle of two or more words also finds declarations whose names or nearby comments hold those words, from each Rust, Python, JavaScript, TypeScript, Go or Java file's parsed structure; nothing is sent anywhere, no model is used and nothing is stored. `fs.list` lists one folder. `cmd.run` starts a program directly, without a shell, in the working directory, with only `PATH`, `HOME`, `LANG`, `LC_ALL` and `TMPDIR` from your environment, and stops it after two minutes. Nothing limits what that program does while it runs. `web.fetch` fetches `http` and `https` URLs only. In `ask` mode it asks first and shows the whole URL, because a URL can carry data off your machine. A redirect to another host is asked about again, and refused when there is no terminal to ask on. It refuses this machine's own addresses and the link-local range, which includes the cloud metadata address.
- **Permission.** The permission mode decides what Zaru asks about. In `yolo` mode it asks nothing, so a model can also change which validators are approved; use `yolo` only for a directory and a task you trust entirely.
- **Validators run only after you approve them.** The commands in a project's `./zaru.toml` are shown to you and run only once you say yes, and you are asked again when they change. The approval is kept under `~/.zaru/`, never in the project, and the permission mode does not skip it.
- **Runtime tiers.** A runtime tier is how much of the 100monkeys platform Zaru uses. The default is `bare`, which uses none. `contained` and `linked` can be selected but are not built yet: at every tier, tool calls run directly on your machine. Zaru prints the not-a-sandbox warning at every tier, and at `contained` and `linked` it adds that the tier is not built yet and changes nothing about how tool calls run. `zaru runtime` says the same.
- **What the model provider receives.** A short system prompt, your task, the conversation so far, the tool descriptions, and the result of every tool call, including the contents of files read, command output and fetched pages. The system prompt states the working directory, the operating system, the date, the tool names and the permission mode; if a system prompt is read from a Carbon Forge page (`persona.path`), that page is sent instead. Zaru removes the values of the keys and tokens it has stored from this. When it cannot read them (no keyring and no `ZARU_CREDENTIAL_KEY`) and the task needs none of them, it says so and goes on without removing them. It does not look for any other secret.
- **What stays on your machine.** Settings, stored keys and sessions are under `~/.zaru/`. Keys and tokens are in `~/.zaru/credentials.json`, encrypted with AES-256-GCM; the encryption key is in the OS keyring or in `ZARU_CREDENTIAL_KEY`. Session files are readable only by you and are kept until you delete them with `zaru sessions rm`.

### Known limitations

- Only three provider kinds work: `gemini`, `ollama` and `openai-compatible`. `anthropic` and `aegis` are recognised but have no client.
- `zaru learned` and `zaru inbox` are placeholders.
- The `contained` and `linked` tiers contain nothing (see above).

## Exit codes

| Code | Meaning |
| --- | --- |
| 0 | The command succeeded. |
| 1 | The work failed: the validators never all passed. |
| 2 | Something you can fix: a missing key or model, a bad setting, an unknown command. The message says what to change. |
| 3 | A problem outside Zaru, such as the network or the provider. The message says whether to wait. |
| 4 | The current runtime tier cannot do what was asked. |
| 70 | A bug in Zaru. The message says how to report it. |
| 128 + n | The session or task was ended by signal n: 143 for `SIGTERM`, 130 for `SIGINT`, and 129 for `SIGHUP` or a terminal that was closed. What was running is stopped first, and the session can be resumed. |

## Development

```sh
cargo fmt --all --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --locked
scripts/check-license-headers.sh
python3 scripts/check-crate-boundaries.py
```

These are the checks CI runs, together with `cargo doc` and a sign-off check. Unset `NO_COLOR` before you run the tests, because one test checks colour output. Every commit needs a `Signed-off-by` line (`git commit -s`); see [CONTRIBUTING.md](CONTRIBUTING.md). Contributors and coding agents start at [CLAUDE.md](CLAUDE.md).

## Licence

Apache-2.0. See [LICENSE](LICENSE), [NOTICE](NOTICE) and [THIRD_PARTY.md](THIRD_PARTY.md).

Linux 系统；Rust 1.98.1（由 rust-toolchain.toml 固定）；C 编译器 cc；首次构建需访问 crates.io。需自备模型：Google Gemini API Key、Ollama 服务或任意 OpenAI 兼容 chat completions 服务（服务是否收费待核验）。无钥匙串的环境需自行设置 ZARU_CREDENTIAL_KEY。是否支持国内网络环境与国内模型，待核验。