zagent

中文说明 · Documentation

A command-line AI agent built with Zig. It works on your machine through tools — reading and editing files, searching a project, running commands, calling APIs — and keeps the conversation, the plan and its notes between runs.

• Interactive REPL — a full-screen conversation with the prompt pinned to the bottom and a prompt history that ↑/↓ recall across runs; Ctrl+Z suspends and fg redraws the whole record. Details
• Single-query mode — pass a question directly as a CLI argument
• Tool use — the agent runs tools to do the work: bash, read, write, edit, apply_patch, ls, rg/grep, fd/find, web_search, web_fetch, ask_user, plan, memory_save/memory_search and announce_task. Tools · Searching · Patching · Web search and fetching
• Multi-turn tool chaining — the agent loops until the task is complete. The agent loop
• Sub-agents — hand one self-contained task to a second agent and watch it: every self-check interval it reports its progress on the terminal, and at its deadline it stops and says what is done and what is left. Sub-agents
• MCP servers — start the servers described in mcp.json and give their tools to the model beside the built-in ones, loaded on demand. MCP servers
• Session plan — a checklist of the work in progress that survives /clear and comes back with a resumed session. Plan
• Durable conversations — every launch is a saved session: /new starts another, --resume <id> picks one up with its context and plan. Sessions
• Memory — durable notes scoped to the workspace, written by the model when a decision or convention matters, searched on demand. Memory
• Choice menus — when a request is ambiguous, the agent offers concrete options instead of guessing, with the recommended one marked. Choices
• Completion judged by the model — a final answer ends the turn; the model must verify its work and say what is unfinished. Completion status
• Thinking panel — the model's reasoning scrolls in one dim row above the prompt while it thinks, stays a few seconds into the answer, then folds into one line. Thinking
• Live progress — waiting, running a tool and watching a sub-agent each get one animated line with the time so far. Live progress
• Debug tracing — --debug records every request, response, tool call and result, and renders the run as one self-contained HTML flowchart to read when something went wrong. It is a build option, so a release binary carries none of it. Debug tracing
• Provider presets — openai, deepseek and openai-compatible for the Responses API, anthropic and anthropic-compatible for the Anthropic Messages API, and codex for a ChatGPT subscription. Providers · ChatGPT / Codex
• Markdown rendering and ANSI colour — styled in a terminal, raw markdown when piped. Rendering

• Zig 0.17.x
• An API key and base URL for a Responses- or Messages-compatible endpoint

zig build

The binary is written to zig-out/bin/zagent. zagent --help lists the flags.

export DEEPSEEK_API_KEY='your key'      # or OPENAI_API_KEY, see Providers
zagent                                  # interactive session
zagent "what is the current date and time?"   # one query, one answer
zagent --resume <session-id> "Continue the task"

Exported keys alone are enough: DEEPSEEK_API_KEY selects the deepseek preset, OPENAI_API_KEY selects openai, ANTHROPIC_API_KEY selects anthropic. For any other vendor on the Responses API:

export AI_PROVIDER=openai-compatible
export AI_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
export AI_MODEL=qwen-plus
export AI_KEY='your key'
zagent

A vendor speaking the Anthropic Messages API instead:

export AI_PROVIDER=anthropic-compatible
export AI_URL=https://api.moonshot.cn/anthropic
export AI_MODEL=kimi-k2-turbo-preview
export AI_KEY='your key'
zagent

The config file, the full environment table, the token budget and the retries are in Configuration. Start with a copy of zagent.example.conf in $XDG_CONFIG_HOME/zagent or ~/.config/zagent; mcp.example.json shows the optional MCP servers.

An explicit AI_URL, AI_MODEL or key always wins over the preset, and AI_PROVIDER unset is autodetected from the exported keys. Details, including autodetection and the mapping of both protocols: Providers.

AI_PROMPT_CACHE_RETENTION can be set in the environment or config file (environment wins). It defaults to unset: no explicit cache field is sent. It accepts only in_memory or 24h; other values fail configuration loading with InvalidPromptCacheRetention. Confirm support before enabling it on a compatible endpoint. Automatic server-side caching may work without it. See the example config.

Read/search pages hold about 7.5 KiB, and any tool result larger than 8 KiB — shell output, a fetched page, an MCP answer — is cached in the run's scratch folder and replaced by a 4 KiB preview naming a cache ID that ccr_retrieve reads back. Cached output is named after its content, so identical output is kept once. Long shell output keeps both ends of stdout and stderr and marks omitted content. Redirect large output to a file and read pages when the omitted middle matters. Debug request events include input bytes, tool schema bytes and a SHA-256 tool-set fingerprint; turn summaries distinguish missing cache reports from a reported zero.

Enter submits, Shift+Enter inserts a newline (Ctrl+J where the terminal does not report it), Ctrl+Z suspends, Ctrl+D exits, Esc interrupts a running task, and / or @ open the completion popups. The keyboard in full: Interface.

Tools and local MCP servers run directly on the host with your permissions, environment and network access — there is no sandbox and no command filter. Start zagent in the intended project, approve each directory once when it asks, and only run tasks you trust. Read Security and state once before pointing it at anything unfamiliar.

zig build test              # unit tests
zig build test-integration  # builds the binary, runs the Python suites in tests/

Both are described in Development.