Stop Your AI From Grading
Its Own Code

Open iTerm2 once to complete initial setup, then continue in it for the rest of this guide.

Pro or Max subscription required for browser OAuth. No API key needed with this method.

Example (16 GB tier):

The Ollama block in zshrc-snippet.sh adds these aliases. Append the relevant tier block to your ~/.zshrc (see Step 6 for full snippet instructions).

Open iTerm2 → Settings → Profiles (⌘,). Click the + button four times. Double-click each "New Profile" name to rename it:

All 4 profiles created and named in the sidebar

For each profile, click the Colors sub-tab:

• Click the Background swatch in the "Defaults" row. In the macOS colour picker, switch to Hex mode (sliders icon → dropdown at bottom) and enter the hex value from the table above.
• Scroll down to "Tab:", tick "Use custom tab color", and set the accent colour.

Scrolled down in Colors tab — Tab colour and Badge colour visible at the bottom

Click the General sub-tab for each profile:

• Title: Click the dropdown. Under "Foreground Job", uncheck "Job Name" (leave only "Session Name" checked under "Name"). This prevents the tab title from showing -zsh or (claude) after the role name.
• Badge: Type the role name (AUDIT, IMPL, PROMPT, or PLAN). This overlays a faint watermark on the pane background.

Then click the Text sub-tab and set font to JetBrains Mono 13pt (or Menlo 13pt).

General tab — badge set to "AUDIT", command and initial directory configured

In each profile → General sub-tab → change the Command dropdown from "Login Shell" to "Custom Shell" and paste the corresponding command:

Replace your-project with your actual project directory name.

Still in the General sub-tab, find Initial directory below the Command field. Change from "Home directory" to "Directory:" and enter the full path:

Open your shell config file and paste this block at the very bottom:

Then run source ~/.zshrc in each pane to apply.

1. Open a new window with the CC-AUDIT profile.
2. ⌘D — split right. Right-click the new pane → Edit Session → change profile to CC-PROMPT.
3. Click back on the left pane (AUDIT). ⌘⇧D — split down. Change the new pane to CC-IMPL.
4. Click on the top-right pane (PROMPT). ⌘⇧D — split down. Change the new pane to CC-PLAN.

Final result — 4 panes with coloured prompts, badges, and distinct background tints

1. Window → Arrangements → Save Window Arrangement — give it a name (e.g. your project name).
2. Go to iTerm2 → Settings → General → Startup and set "Window restoration policy" to "Open Default Window Arrangement".
3. Back in the menu: Window → Arrangements → Save Window Arrangement once more — this saves it as the default arrangement that the startup policy will use.

Window → Arrangements → Save Window Arrangement

Settings → General → Startup → "Open Default Window Arrangement"

Every code change follows this pattern across panes:

When AUDIT finds an issue, copy its output and paste into IMPL:

• Re-anchor on long sessions: "Re-read CLAUDE.md and confirm the project rules. Then..."
• Scope AUDIT reviews: "Focus ONLY on src/auth.py. Do not read any other files."
• Clear stale context: /clear resets the conversation entirely.
• Compress instead: /compact summarises and frees context without losing history.
• State sync before review: Run /clear in the AUDIT pane before starting a review pass on code that IMPL just wrote. This ensures AUDIT reads current file contents, not stale versions cached in its context.

Use a project-specific prefix: MYPROJECT-AUDIT, MYPROJECT-IMPL, etc. Or keep DEV-* and just change the directory.

Point to the new project path in each profile's General tab.

Add matching entries in both case blocks for the new names:

Name it after the project (Window → Arrangements → Save Window Arrangement). To switch between projects later, use Window → Arrangements → [arrangement name] — iTerm2 opens the saved 4-pane layout for that project in a new window.

Open (or create) ~/.claude/settings.json. Copy the "hooks" block from hooks/settings.json.example into the top level of the JSON object. All "command" values use $HOME — Claude Code does not expand ~.

The example also includes "env": {"CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50"}. This tells Claude Code to auto-compact the conversation context when it reaches 50% of the context window. Without this, Claude waits until near the limit before compacting, which can cause abrupt context loss mid-session. Set to "0" to disable, or remove the "env" block entirely to use the default threshold.

Both aliases are only defined when $ITERM_PROFILE == CC-IMPL. They are no-ops in other panes.

Never send work to AUDIT until gate passes.

Append a new entry at the end of every session. Never overwrite old entries. Minimum viable format:

Real example:

In your ~/.claude/CLAUDE.md (see Step 14), add a Session Continuity instruction: "At the start of every session, read the last 60 lines of SESSION_LOG.md and surface the most recent 'Next:' items before doing anything else."

Claude Code merges both automatically — global first, project-specific second.

Claude Code registers MCP servers via claude mcp add, not by reading a config file from disk. The included .mcp.json.example is reference JSON if you need claude mcp add-json instead.

1. Install the binary:
   brew install github-mcp-server
   Or see github.com/github/github-mcp-server for other install methods.
2. Register with Claude Code (user-scope — available in every project):
   claude mcp add github -s user \

   -e GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_readonly_token \

   -- $(which github-mcp-server) stdio
   Generate a read-only PAT at github.com/settings/tokens with scope public_repo (or repo for private-repo access). Recommended expiry: 90 days.
3. Verify: claude mcp list | grep github

Run /reflect at the end of any IMPL or AUDIT session. Claude reads the recent git log and diff, then outputs a formatted table of suggested CLAUDE.md additions — ready to copy and paste.

Three skills that load relevant instructions automatically when Claude is doing review or test work:

Skills activate automatically — no manual invocation needed.

The installer verifies fswatch, osascript, and iTerm2 are present; copies pane-handoff.sh (the watcher) and enforce-handback.py (a Stop hook) to ~/.claude/hooks/; copies the /start-impl and /start-audit commands to ~/.claude/commands/; installs a launchd agent at ~/Library/LaunchAgents/com.user.handoff.plist (auto-starts at login, restarts on crash); and arms routing.

To uninstall: ./handoff/install.sh --uninstall

This defines the user-facing API, available in every pane:

Pick a scope name per project (lowercase, no spaces — e.g. myapp). In the IMPL pane, inside Claude:

In the AUDIT pane, inside Claude: handoff-use myapp, then the /start-audit slash command, then handoff-claim-audit. Confirm both bindings and smoke-test:

AUDIT → IMPL — the AUDIT pane writes a directive (via its Bash tool) and ends it with the confirmation line → handed off:

IMPL → AUDIT — after gate passes, IMPL hands back, ending with → handed back:

The confirmation lines are load-bearing: the enforce-handback.py Stop hook (a script Claude Code runs at the end of each turn — see Step 14) blocks IMPL from claiming “→ handed back” in chat without actually writing the file — the failure mode that otherwise leaves AUDIT waiting forever on a loop that silently broke.

Either pane can pause its own project’s loop by writing the scoped sentinel. Contents must name the trigger and the human action required:

This writes ~/.claude/handoff/HALT.myapp. The watcher logs ⛔ HALT scope=myapp, fires a macOS notification, and both panes in that scope stop before doing anything else. Other projects keep flowing — HALT is per-scope, there is no global pause. Only a human resumes it:

If a paste doesn’t arrive, ask three questions in order — then read /tmp/handoff.log:

Edited the watcher script? It does not hot-reload — pkill -f pane-handoff.sh and launchd respawns it within ~1s.

The SESSION_LOG pattern (Step 16) carries context forward in time within one project. It does not carry context sideways — AUDIT never learns what you told IMPL, and nothing crosses project boundaries. In practice that means re-explaining “we use pnpm, not npm” or “never run db:reset against staging” in every pane, every session.

Sigil closes that gap with hooks that run inside every Claude Code session, regardless of pane, model, or permission mode:

Because memory lives in a local database rather than in any one session, all four panes share it — and it is MCP-native, so the same memory is available to other MCP clients (Cursor, Codex CLI) if you use them alongside this setup.

Installation is a one-liner, then an interactive wizard. Follow the upstream README at github.com/Anmol-Srv/sigil for current instructions; as of this writing:

The sigil init wizard walks you through four choices: a database (Postgres — local or managed), an LLM provider for fact classification (OpenRouter, OpenAI, Anthropic, Ollama, or your Claude subscription), an embedding provider (OpenAI, Voyage, or Ollama), and hook wiring — it auto-detects Claude Code, installs its hooks into ~/.claude/settings.json, and registers MCP servers for other clients. It merges alongside the hooks from Step 14 without touching them.

Verify the loop end-to-end: open any pane with cc, submit a prompt, and confirm memory search fires without a timeout warning. Then check claude mcp list shows Sigil connected.

The hooks do the routine work unprompted. Manual interaction comes down to three commands, runnable from any pane (or inside Claude Code with ! shell-exec):

The hooks fire identically everywhere, but there’s a natural division of labor:

New project — spend two minutes on day 1 telling Sigil what the project is. Every later prompt, in every pane, has it on tap:

Existing project — no migration needed; the hooks fire regardless. Teach it project specifics as you hit them, and optionally bulk-seed from the docs you already maintain:

Sigil extracts atomic facts and de-duplicates against existing memory. Run sigil facts afterward to spot-check what landed. Your SESSION_LOG (Step 16) and CLAUDE.md files (Step 17) keep working exactly as before — Sigil owns the cross-session, cross-project layer; it doesn’t replace either.

1. Download from the Mac App Store: search “Draw Things AI Image Generator”.
2. Open the app and let it download a base model (~2–4 GB).
3. Prompt directly in the app’s text field. Drag and drop an image as reference.

Recommended starting model: SDXL Turbo (fast) or Flux Schnell (higher quality). Models are downloaded in-app — no terminal commands needed.

Symptom: echo $ITERM_PROFILE returns nothing. The cc alias falls through with no model flags.

Cause: Old iTerm2 version (< 3.3) or the pane was opened before the profile was applied.

Fix:

• Update iTerm2 to 3.3 or later (Help → Check For Updates).
• Close and reopen the pane by selecting the profile explicitly: Profiles → [your profile name] → Open in current tab.
• Confirm with: echo $ITERM_PROFILE — should print CC-AUDIT, etc.

Symptom: which cc shows /usr/bin/cc. Typing cc outputs compiler error messages.

Fix: Rename the alias in ~/.zshrc. Replace all 4 alias cc= occurrences with alias cl= (or any name you prefer), then reload:

Check 1 — Hook files exist:

Check 2 — Python 3 is available:

Check 3 — settings.json is valid JSON:

Symptom: Claude is blocked and won't proceed. The circuit-breaker tripped after 3 consecutive tool failures.

Fix A — Start a new session: Press Ctrl+C, then type cc. The session-start-reset.py hook fires automatically on session start and resets the counter.

Fix B — Reset the state file directly:

Symptom: gate exits non-zero immediately or pytest reports collected 0 items.

• Venv not active: Run source venv/bin/activate (or source .venv/bin/activate) before running gate.
• pytest not installed: which pytest should point inside your venv. If not: pip install pytest.
• No test files yet: Add a placeholder so the intent is explicit: touch tests/test_placeholder.py with a single passing test.

The protect-git-push.py hook blocks Claude from running git push autonomously. You can always push directly from a regular terminal prompt — hooks only intercept tool calls inside a Claude Code session.

Symptom: After npm update -g @anthropic-ai/claude-code, typing cc errors with an unknown flag message.

1. Run claude --help to see current supported flags.
2. Update the alias block in ~/.zshrc to match, then source ~/.zshrc.
3. Most stable flags: --model and --effort have been stable across versions. --permission-mode values are also stable. Check the Claude Code release notes for breaking changes.

Run claude --version to check your installed version. This guide was verified against v2.1.81 (March 2026).