ZIZOU docs

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

Operating Modes: Build vs Plan

Zizou supports two execution pipelines designed for different workflow complexities:

1. Build Mode (● Build — Default)

• Fast, One-Shot Execution: Ideal for single-file edits, quick bug fixes, and concise tasks.
• Pipeline: Prompt → Synthesize single step → Stream tool execution → Verify result.
• Escalation Safety Net: If execution touches more than 3 files or verification fails, Zizou deterministically prompts you to escalate to Plan Mode.

2. Plan Mode (◆ Plan — --plan or /plan)

• Structured Multi-Step Pipeline: Designed for complex features, multi-file refactors, and architectural changes.
• Pipeline: Prompt → Clarify (interactive Q&A) → Plan (ordered JSON plan) → User Confirmation (Y/n) → Execute each step → Verify each step.
• Dependency Ordering: Enforces strict topological sorting so setup and file scaffolding steps execute before consumers.

Context Budgets & Reasoning Levels

Context Budgets (/context <mode>)

Controls how much project structure is injected into the system prompt:

• light: Minimal context. Repo map is excluded for the Executor to keep context lean. (Clarifier and Planner always retain the repo map to prevent scaffolding errors).
• default: Includes the full pre-computed codebase symbol index (Repo Map).
• max: Maximum context inclusion for deep codebase reasoning.

Reasoning Levels (/reasoning <level> or /expert)

Presets tune inference temperature and output window tokens based on task complexity:

• low (fast preset): Speed & low cost (Temp: 0.2, Max Tokens: 1,024).
• medium (balanced preset): Standard balance (Temp: 0.2, Max Tokens: 2,048).
• high (high preset): Maximum depth & deterministic output for complex code generation (Temp: 0.1, Max Tokens: 4,096).

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