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.

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