ZIZOU docs

Everything you need to run, extend, and understand Zizou — the AI coding agent that lives in your terminal.

Zizou comes with several built-in slash commands you can use in the chat bar to configure your agent on the fly.

Modes

Auto is the default. Pinning any other mode skips the routing call entirely, so a pinned mode costs exactly what it always did.

/auto — Classify each prompt and route it (the default).
/chat — Conversation only. No tools at all.
/ask — Read-only. Answers questions about your code, never writes.
/build — Fast single-step execution.
/plan — Plan → review at the gate → execute → verify.

Each also has a CLI flag: --auto, --chat, --ask, --build, --plan. zizou plan "…" still works as a positional subcommand.

Effort

/effort — Show the current level and what each one does.
/effort <fast|balanced|max> — Set it for this session.
/fast, /balanced, /max — Shorthands for the above.

One dial: it sets the model, the sampling parameters and the tool-round cap together. A /model pin overrides the model effort would choose.

Models & providers

/keys — Interactive setup: switch AI providers and update API keys.
/model <provider> [name] — Switch the active provider, optionally pinning a model.
/models — List every available model option for all providers.
/modelid <name> — Set a custom model ID for the current provider.
/ollama <url> — Set the Ollama base URL.
/ollama ctx <n> — Cap the context window requested from local models.

Context

/add <filepath> — Pin a file's contents permanently to context (alias: /file).
@ — Type @ in the input for fuzzy file search, then Enter to insert the path.
/init — Create a ZIZOU.md for project settings, layout and conventions.
/prompt — Dump the full system prompt sent to the LLM.
/skills — List available custom agent skills.

Running turns

Esc — Stop the turn in flight. The request is cancelled at the provider, not just hidden from you. Anything already written to disk stays; /undo rolls back the last step. Esc works during a permission prompt too, where "deny this one write" and "stop the whole run" are different things.

History & safety

/permissions — View session-cached file/command permissions, or clear them (/permissions clear).
/checkpoint — Manage checkpoints (list, diff, restore, branch, switch, delete, revert).
/undo — Undo the last step's file changes.
/redo — Redo the last undone step.
/session — Manage parallel sessions (list, switch <name>, new, delete).
/export — Export the conversation transcript to markdown.
/clear — Reset conversation history & session permissions.
/help — Show available commands, the active mode, effort and model.
/exit — Close Zizou.

New Features

Step-Level Undo/Redo

Zizou now supports step-level undo and redo operations, allowing you to revert file changes at the granularity of individual execution steps:

/undo — Reverts the file changes from the last executed step. If a step created a file, /undo deletes it. If a step deleted a file, /undo restores it.
/redo — Re-applies changes that were previously undone.
Undo/redo state is persisted in .zizou/ and cleared when switching sessions.
Multiple sequential /undo calls walk back through multiple steps.

@ File Search

Type @ in the chat input to trigger fuzzy file search:

Press @ and start typing to filter project files.
Use arrow keys to navigate through matches.
Press Enter to insert the selected file path into your prompt.
Supports multiple @ references in a single prompt.
Respects .gitignore patterns (excludes node_modules, .git, etc.).
File index is cached and debounced for performance on large projects.

Model-Tier Indicators

Zizou now displays which model tier handled each step:

[local] — Green tag for local execution (Ollama).
[hosted] — Yellow tag for cloud-based providers (Anthropic, OpenAI, Groq, Google, etc.).
Tags appear in step progress and verification displays.

Cost Tracking

Running cost is displayed in the status bar and updated after each model call:

Shows accumulated cost in USD based on actual token usage from the AI SDK.
Uses per-model rate tables for accurate calculation.
Unknown models are excluded from the total (shown as "unpriced" in logs).
Rates are easily updatable in a single configuration file.

ZIZOU.md Project Conventions

You can now create a ZIZOU.md file at your project root to declare project-specific conventions:

Content is automatically injected into the planner's context with clear delimiters.
Use this to declare scope guardrails, path conventions, or coding standards.
Example: "Never touch src/legacy/ directory without explicit permission."
Absence of ZIZOU.md is a silent no-op (no errors or warnings).

LLM Compatibility

Zizou (Phase 1) is built on top of the Vercel AI SDK, meaning it is provider-agnostic. Out of the box, it supports:

Anthropic — High-quality reasoning (Claude 3.5 Sonnet). Requires an API key.
OpenAI — GPT-4o capabilities. Requires an API key.
Groq — Extremely fast inference for Llama 3 models. Requires an API key.
Google — Gemini capabilities. Requires an API key.
OpenRouter — Access a massive ecosystem of models through a single API key.
Ollama — 100% free, local execution. Ollama exposes an OpenAI-compatible API on http://localhost:11434/v1. No API key needed.

Running local models

/models reads your installed models straight from the Ollama server and shows what actually matters for each one:

BASH

ollama      - installed locally (v0.32.1):
              qwen3:4b 4.0B Q4_K_M  [tools, thinking, 256k ctx]
              gemma4:e4b 8.0B Q4_K_M  [tools, thinking, 128k ctx]

The tools badge is the one to check. A model without it cannot emit native tool calls, so Zizou has to scrape them out of plain text — unreliable for anything past a single edit. /model ollama <name> warns you when the model you pick lacks it, and tells you which of your installed models has it.

With no model pinned, /effort picks from what you have installed: fast takes the smallest tool-capable model, max the largest. Pinning a model with /model ollama <name> or /modelid <name> overrides that, and /effort then only changes the token and step budgets.

Context window

This is the setting that most often makes a local model look worse than it is. Ollama defaults to a 4096-token context. Zizou's system prompt plus the JSON Schema for its 13 tools is most of that before your message is added, and Ollama truncates silently rather than erroring — so the model can receive its own tool definitions cut in half and then appears to "not support tool calls".

Zizou requests a larger window per request and reads back what was actually loaded. If your Ollama version ignores the request, you get a warning naming the fix:

BASH

OLLAMA_CONTEXT_LENGTH=16384 ollama serve

/ollama ctx <n> adjusts the ceiling Zizou asks for. Higher costs memory — the KV cache scales with it — which is why it is capped rather than simply using each model's advertised maximum. qwen3:4b advertises 262144; asking for that on a laptop trades a truncation bug for an out-of-memory crash.

To connect to any of these, run /keys inside the CLI, or export an environment variable:

$export ANTHROPIC_API_KEY="sk-ant-..."

$export OPENAI_API_KEY="sk-proj-..."