ZIZOU docs

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

Operating Modes

Zizou has one pinned mode and four execution routes. The default pin is Auto, which reads each prompt and picks the route for you.

Auto (◇ Auto — the default)

Auto classifies your prompt with one small, fast model call, then runs the route it picks. The badge shows both — Auto → Build — so you can always see what it chose.

The classification call happens only in auto mode. Pin any other mode and no router call is made, so a pinned mode costs exactly what it always did.

The router is a guess, and is treated as one:

• Low-confidence guesses resolve toward the cheaper mistake. An uncertain plan runs as build; an uncertain chat runs as ask.
• A routed plan still stops at the gate, where a wrong route is one keystroke to redirect.
• If the router times out or the provider is down, the turn continues on a deterministic fallback. It never fails your prompt.

Switch with /auto, or the --auto flag.

Chat (○ Chat — /chat or --chat)

Conversation. Nothing on disk can change.

Pinned /chat has no tools at all — an explicit pin means "just talk". Reached via auto, chat keeps read-only tools, so a message like "hey, is this repo on React 19?" can check instead of guessing.

Ask (? Ask — /ask or --ask)

Questions about your codebase. Read-only tools — readFile, glob, grep, listDir — and nothing else: it can look at anything and change nothing.

This is the route for "how does X work", "where is Y", "why is this failing". Answers cite what they found as path:line.

Build (● Build — /build or --build)

Fast, one-shot execution for single-file edits, quick fixes and concise tasks.

• Pipeline: Prompt → synthesize a single step → stream tool execution → verify.
• Scope hint: if a step touches more than 3 files, Zizou prints one advisory line mentioning plan mode. It does not prompt, block, or restart — the work is already on disk.

Plan (◆ Plan — /plan, --plan, or zizou plan "…")

Structured multi-step work: features, multi-file refactors, architectural changes.

• Pipeline: Prompt → ordered plan with stated assumptions → the gate → execute each step → verify each step.
• Dependency ordering: topological sort, so scaffolding runs before the code that consumes it.
• No clarifying questions. The planner decides anything you left open and declares those decisions as assumptions. The gate is where you correct them.

The Plan Gate

Before any step runs, Zizou shows you the plan: its assumptions, its steps, and every file each step will touch, marked + for a new file and ~ for one that already exists. When auto chose plan, it also shows why.

Those markers are the point. "It is about to create chess.html at the repo root" is visible before approval, while fixing it costs one line.

The gate takes:

| Input | What happens | |---|---| | y | Run the plan | | n | Cancel. Nothing is written. | | b | Run the original prompt as a single build step instead | | a | Answer the original prompt instead — nothing is written | | anything else | A correction. Re-plans with your note and comes back here. |

That last row matters most. Free text is a correction, not a rejection — typing put it in src/games/, not the root revises the plan in place. The gate used to accept y/n only, so fixing one wrong assumption meant cancelling and retyping the entire request.

Where Files Go

Two rules are built into the agent's instructions:

• Look before you write. New files go beside the files of their kind that already exist. The workspace root is for files that belong at a root by convention — README, package.json, tsconfig — not for a new app or component. A multi-file artifact gets its own directory.
• Edit, don't recreate. Before creating a file at a path that does not exist, the agent searches for the file that already does that job. When writeFile is about to create something whose name matches an existing file, the confirmation prompt lists those files so you can catch a near-duplicate before it is written.

A ## Layout section in your ZIZOU.md overrides both. Run /init to get a template with one.

Effort (/effort <level>)

One dial for speed versus quality. It sets the model, the sampling parameters and how many tool rounds the agent gets — because those are the same decision.

• fast: small model, little searching. Quick edits and questions.
• balanced: mid model, normal searching. The default.
• max: strongest model, thorough searching. Hard or wide work.

Shorthands: /fast, /balanced, /max. A /model pin overrides the model effort would choose. Put effort: max under ## Agent in ZIZOU.md to make it stick for a project.

The router ignores this dial and always uses the fast tier — picking between four labels does not need your strongest model.

Session Permissions & Loop Hardening

Session-Level Permission Caching (/permissions)

• Single Prompt Per Target: When you approve a file (read/write/edit/delete) or shell command during a session, Zizou caches that permission.
• Auto-Approval: Subsequent operations targeting the same file or command within the session execute automatically without repeated prompts.
• Management: View active permissions or reset them anytime using /permissions or /permissions clear.

Tool-Call Loop Hardening

• Harness-Enforced editFile Recovery: Caps consecutive editFile failures on the same file at 2 attempts. On the 2nd failure, Zizou forces a fallback to writeFile with the full file content to stop invalid string-matching loops.
• Duplicate Tool-Call Blocking: If the LLM retries an identical (toolName, args) call that previously failed, the harness intercepts it with a synthetic BLOCKED notice, forcing the model to read the file or adjust its strategy.

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).