A minimalist, file-based autonomous agent runner. Orchestrates claude to scout, plan, code, and verify tasks using the file system as memory.

The Philosophy:

1. Files are Database: No SQL, no vector stores, no hidden state.
2. Markdown is API: Plans, logs, and context are just markdown files you can read and edit.
3. Aggressive Cleanup: Designed for legacy codebases. It deletes old code rather than deprecating it.
4. Contract First: Enforces architectural rules via a "psychological linter."
5. Slow is Fast: Upfront planning costs tokens now to save thousands of "debugging tokens" later.

TLDR: Treat LLMs as stateless functions and check their work. Run zen docs/feature.md --reset.

1. Prerequisites You need the Claude CLI installed and authenticated.

npm install -g @anthropic-ai/claude-cli
claude login

2. Install Zen

pip install zen-mode
# OR copy 'scripts/zen.py' and 'scripts/zen_lint.py' to your project root.

3. Run a Task

# Describe your task
echo "build a python web scraper that's robust -- use whatever deps are best. add tests and update requirements." > task.md

# Let Zen take the wheel
zen task.md

Zen Mode breaks development into five distinct phases. Because state is saved to disk, you can pause, edit, or retry at any stage.

.zen/
├── scout.md      # Phase 1: The Map (Relevant files & context)
├── plan.md       # Phase 2: The Strategy (Step-by-step instructions)
├── log.md        # Phase 3: The History (Execution logs)
├── backup/       # Safety: Original files are backed up before edit
└── ...

1. Scout: Parallel search strategies map the codebase.
2. Plan: The "Brain" (Opus) drafts a strict implementation plan.
3. Implement: The "Hands" (Sonnet) executes steps atomically.
4. Verify: The agent runs your test suite (pytest/npm/cargo) to confirm.
5. Judge: An architectural review loop checks for safety and alignment.

Since state is just files, you are always in control:

• Don't like the plan? Edit .zen/plan.md. The agent follows your edits.
• Stuck on a step? Run zen task.md --retry to clear the completion marker.
• Total restart? Run zen task.md --reset.

Real-time cost auditing. You see exactly how many tokens were spent on planning vs. coding.

[COST] Total: $0.71 (scout=$0.07, plan=$0.13, implement=$0.26, verify=$0.08, judge=$0.16, summary=$0.00)

> zen .\cleanup.md --reset
Reset complete.

[SCOUT] Mapping codebase for .\cleanup.md...
  [COST] haiku scout: $0.0712 (3461+2271=5732 tok)
  [SCOUT] Done.

[PLAN] Creating execution plan...
  [COST] opus plan: $0.1335 (731+846=1577 tok)
  [PLAN] Warning: CONSOLIDATE: 3 test steps found. Combine into 1-2 steps.
  [PLAN] Done. 4 steps.
  [BACKUP] workers\scraper.py
  [BACKUP] requirements.txt
  [BACKUP] scripts\run_scraper.py
  [BACKUP] test_urls.json
  [BACKUP] api\db\models.py
  [BACKUP] api\v1\tests\conftest.py
  [BACKUP] api\v1\routes.py
  [BACKUP] test_results.txt

[IMPLEMENT] 4 steps to execute.

[STEP 1] Update requirements.txt with async, retry, and testing depen...
  [COST] haiku implement: $0.0187 (12+483=495 tok)
  [COMPLETE] Step 1

[STEP 2] Rewrite workers/scraper.py with async support and robustness...
  [COST] haiku implement: $0.0600 (28+3155=3183 tok)
  [COMPLETE] Step 2

[STEP 3] Create workers/tests directory and test_scraper.py with unit...
  [COST] haiku implement: $0.0974 (92+5643=5735 tok)
  [COMPLETE] Step 3

[STEP 4] Verify all tests pass and scraper integrates with run_scrape...
  [COST] haiku implement: $0.0840 (757+2428=3185 tok)
  [COMPLETE] Step 4

[VERIFY] Running tests...
  [COST] haiku verify: $0.0824 (96+2049=2145 tok)
  [VERIFY] Passed.

[JUDGE] Senior Architect review...
  [JUDGE] Review loop 1/2
  [COST] opus judge: $0.1609 (2+647=649 tok)
  [JUDGE_APPROVED] Code passed architectural review.
  [COST] haiku summary: $0.0043 (1+124=125 tok)
  [COST] Total: $0.713 (scout=$0.071, plan=$0.134, implement=$0.260, verify=$0.082, judge=$0.161, summary=$0.004)

[SUCCESS]

When you run zen init, it creates a CLAUDE.md file in your root (if you don't have one). This is the Psychological Linter.

The agent reads this file at every single step, ensuring consistent architectural decisions across your entire codebase.

## GOLDEN RULES
- **Delete, don't deprecate.** Remove obsolete code immediately.
- **Complete, don't stub.** No placeholder implementations or "todo" skeletons.
- **Update callers atomically.** Definition changes and caller updates in one pass.

## ARCHITECTURE
- **Inject, don't instantiate.** Pass dependencies explicitly.
- **Contract first.** Define interfaces before implementations.
- **Pure constructors.** No I/O, network, or DB calls during initialization.

## CODE STYLE
- **Flat, not nested.** Max 2 directory levels.
- **Specific, not general.** Catch explicit exceptions; no catch-all handlers.
- **Top-level imports.** No imports inside functions.

## TESTING
- **Mock boundaries, not internals.** Fake I/O and network; real logic.
- **Test behavior, not implementation.** Assert outcomes, not method calls.

Add project-specific rules:

• "Always use TypeScript strict mode."
• "Prefer composition over inheritance."
• "Never use 'any'."
• "All API endpoints must have OpenAPI docstrings."

Coding is easy when you start from scratch. It is hard when you have to respect an existing codebase.

Most users lose money with standard AI chats because they pay the "Context Tax." They ask a cheap chatbot to fix a file, but the bot doesn't know the project structure, so it writes code that imports missing libraries or breaks the build. You then spend hours (and more tokens) pasting errors back and forth.

Zen Mode flips this equation. It pays a higher upfront cost to "Scout" your existing code so it doesn't break it.

In the execution log above, Zen Mode performed a 4-step refactor on an existing scraper.

• Total Cost: $0.71
• Human Time: 0 minutes
• Result: It found the files, installed dependencies, wrote the code, created new tests, ran them, and passed architectural review.

For the non-coder: Zen Mode acts like a Senior Engineer pairing with you. It doesn't just write code; it plans, verifies, and cleans up after itself, making software development accessible even if you don't know how to run a debugger.

All environment variables with defaults:

Example:

export ZEN_MODEL_BRAIN=claude-3-opus-20240229
export ZEN_MODEL_HANDS=claude-3-5-sonnet-20241022
export ZEN_SHOW_COSTS=false

The Judge phase (Opus architectural review) is automatically skipped to save costs when:

Always reviewed: Files containing auth, login, payment, crypt, secret, or token in the path.

Override thresholds with: ZEN_JUDGE_TRIVIAL, ZEN_JUDGE_SMALL, ZEN_JUDGE_SIMPLE_LINES, ZEN_JUDGE_SIMPLE_STEPS

If you installed via pip but want to hack the source code:

zen eject

This copies zen.py and zen_lint.py to your project root for local modifications. The zen command will automatically use your local versions.

Zen Mode includes a built-in "lazy coder detector" that runs after every implementation step. It enforces the Constitution by catching sloppy patterns before they ship.

See docs/linter-rules.md for the complete rule reference.

Suppress specific rules when needed:

debug_value = 86400  # lint:ignore MAGIC_NUMBER
print(x)             # lint:ignore  (suppresses all rules for this line)

Create .lintrc.json to disable rules project-wide:

{
  "disabled_rules": ["DEBUG_PRINT", "MAGIC_NUMBER"]
}

# Lint git changes (default)
python -m zen_mode.linter

# Lint specific paths
python -m zen_mode.linter src/ tests/

# Output formats for CI
python -m zen_mode.linter --format json
python -m zen_mode.linter --format sarif  # GitHub Code Scanning compatible

# Show all rules
python -m zen_mode.linter --list-rules

See docs/troubleshooting.md for common issues:

• Agent stuck on step → zen task.md --retry or edit .zen/plan.md
• Lint keeps failing → inline suppression or .lintrc.json
• Judge rejected → check .zen/judge_feedback.md
• Costs too high → --skip-judge or break into smaller tasks