zen-mode 1.0.2

Minimalist autonomous agent runner

Zen Mode 🧘

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.

Prerequisites

1. Install Claude CLI (Required): The agent uses the official Anthropic CLI to interface with the LLM.

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

Installation

Option A: The Package (Recommended)

Best for general use. Zero dependencies.

pip install zen-mode

Option B: The Scripts (For Hackers)

Best if you want to modify the agent's internal logic.

Download zen.py and zen_lint.py from the scripts folder to your project root.

---

Workflow

1. Initialize

Run this in your project root to generate the config.

zen init

Creates .zen/ directory and CLAUDE.md (The Constitution).

2. Define the Task

Create a simple text file (e.g., task.md) describing what you want:

"Refactor the auth module to use JWTs instead of sessions. Delete the old session middleware."

3. Run the Agent

zen task.md

The agent will loop through five phases:

1. Scout: Maps relevant code (writes to .zen/scout.md).
2. Plan: Drafts a step-by-step plan (writes to .zen/plan.md).
3. Implement: Executes steps one by one.
4. Verify: Runs tests to confirm.
5. Judge: Architectural review.

4. Intervention (The "Human in the Loop")

Since state is just files, you are in control:

• Don't like the plan? Open .zen/plan.md, edit the text, and run zen task.md again. It resumes automatically.
• Stuck on a step? Run zen task.md --retry to clear the step completion marker.
• Total restart? Run zen task.md --reset to nuke the .zen folder.

---

The Hidden Token Economy

At first glance, Zen Mode's five-phase process seems token-intensive. In practice, it is net-positive because it eliminates the "Debug Spiral."

Traditional "Shotgun" Approach (~4,700 tokens):

• Generate broken code (1000)
• Debug session identifying issues (1500)
• Fix attempt #1 (800)
• Still broken, more debugging (1200)
• Final verification (500)

The Zen Approach (~2,800 tokens):

• Scout + Plan + Implement (2000)
• Judge phase / Architectural gates (800)

The Result: You spend ~40% fewer tokens to achieve architectural coherence that would usually take 3-4 manual iterations.

---

Advanced

The Eject Button

Started with the package but want to hack the source code?

zen eject

This copies the internal logic (zen.py and zen_lint.py) into your local directory. The zen command will now use your local versions.

Configuration

Env vars (optional):

export ZEN_MODEL_BRAIN=opus       # For planning
export ZEN_MODEL_HANDS=sonnet     # For coding
export ZEN_MODEL_EYES=haiku       # For summaries
export ZEN_TIMEOUT=600            # Max seconds per step
export ZEN_LINTER_TIMEOUT=120     # Max seconds for linter
export ZEN_RETRIES=2              # Max retries per step
export ZEN_JUDGE_LOOPS=2         # Max code review steps

Upgrade After Eject

After ejecting, you're on your own for updates. Compare your local files against the scripts folder to see what changed.