In this guide
01
The 4-Pane Concept
Each pane runs a separate Claude Code session with a dedicated role. The AUDIT pane uses Opus for deep review. Everything else uses Sonnet to keep costs down. A cc alias launches the right configuration automatically.
AUDIT
Opus
Modelopus
Efforthigh
Permissionplan (read-only)
Review completed work. Never generates code. Enforced read-only via --permission-mode plan. Scope reviews with: "Focus ONLY on src/auth.py. Do not read other files."
IMPL
Sonnet
Modelsonnet
Efforthigh
PermissionacceptEdits
Write and edit code. Auto-accepts file edits. Run tests after every change.
PROMPT
Sonnet
Modelsonnet
Effortmedium
Permissiondefault
Refine prompts, templates, and content. Separate from code changes.
PLAN
Sonnet
Modelsonnet
Effortlow
Permissiondefault
Discuss architecture, plan features, review docs. No file writes.
Cost awareness Opus is ~15x more expensive than Sonnet per token. Only use the AUDIT pane for reviewing completed, tested work — never for code generation.
Why iTerm2 over macOS Terminal?
This workflow relies on features the default Terminal doesn't have:
| Feature | macOS Terminal | iTerm2 |
|---|---|---|
| Split panes | Tabs/windows only — no side-by-side splits | Unlimited independent panes in a single tab |
| Named profiles | Basic profiles, no $ITERM_PROFILE env var | Auto-sets $ITERM_PROFILE per pane — the key to role detection |
| Visual identity | Basic themes and transparency | Per-profile backgrounds, tab colours, badges, and 24-bit colour |
| Window arrangements | No saved layouts | Save & auto-restore multi-pane layouts on launch |
| Productivity | Standard find and copy | Paste history, Instant Replay, triggers, shell integration |
Split panes
Terminal Tabs/windows only
iTerm2 Unlimited independent panes in one tab
Named profiles
Terminal No $ITERM_PROFILE env var
iTerm2 Auto-sets $ITERM_PROFILE per pane
Visual identity
Terminal Basic themes only
iTerm2 Per-profile backgrounds, tab colours, badges
Saved layouts
Terminal Not supported
iTerm2 Save & auto-restore on launch
Productivity
Terminal Standard find and copy
iTerm2 Paste history, Instant Replay, triggers
The $ITERM_PROFILE environment variable is especially critical — it's what lets the cc alias automatically launch the right model and permissions per pane, and it survives window arrangement restores.
02
Create iTerm2 Profiles
Create 4 named profiles, each with a distinct background tint, tab colour, and badge so you can instantly tell which pane you're in.
2.1
Create and name 4 profiles
Open iTerm2 → Settings → Profiles (⌘,). Click the + button four times. Double-click each "New Profile" name to rename it:
| Profile Name | Background | Tab Colour | Role |
|---|---|---|---|
| DEV-AUDIT | #0d0b18 | #a855f7 | Code review |
| DEV-IMPL | #080f0b | #22c55e | Implementation |
| DEV-PROMPT | #080e10 | #06b6d4 | Prompt engineering |
| DEV-PLAN | #0d0b00 | #f59e0b | Architecture & planning |
All 4 profiles created and named in the sidebar
2.2
Set background & tab colour
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
2.3
Set title, badge, and font
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
03
Startup Commands & Initial Directory
Each profile needs a startup command (to cd into the project directory and open an interactive shell) and an initial directory setting (as a fallback for window arrangement restores).
3.1
Set the startup command
In each profile → General sub-tab → change the Command dropdown from "Login Shell" to "Custom Shell" and paste the corresponding command:
# DEV-AUDIT
/bin/zsh -c 'cd ~/Desktop/your-project; exec zsh'
# Same command for all 4 profiles — only the directory changes per project.
# Role detection uses $ITERM_PROFILE (set automatically by iTerm2),
# so the startup command doesn't need to set PANE_ROLE.
Replace your-project with your actual project directory name.
Why
exec zsh at the end? It replaces the subshell with an interactive zsh session. Without it, the pane would close the moment you exit Claude Code or any other command.
3.2
Set the initial directory
Still in the General sub-tab, find Initial directory below the Command field. Change from "Home directory" to "Directory:" and enter the full path:
/Users/yourname/Desktop/your-project
Why set both Command and Initial Directory? iTerm2 window arrangement restore doesn't always re-run the startup command, but it always respects the Initial Directory. Setting both ensures you always land in the right folder regardless of how the pane was opened.
04
Shell Prompts & Launch Alias
Add a block to your ~/.zshrc that auto-detects which profile you're in and configures coloured prompts, locked tab titles, and a cc alias to launch Claude Code with the right flags.
4.1
Append to ~/.zshrc
Open your shell config file and paste this block at the very bottom:
~/.zshrc — append at bottom
# ── Multi-pane Claude Code workflow ──
# Uses $ITERM_PROFILE (auto-set by iTerm2 on every
# session, including arrangement restores).
case "$ITERM_PROFILE" in
DEV-AUDIT)
PANE_ROLE="AUDIT"
PROMPT="%F{magenta}[AUDIT]%f %~ %# " ;;
DEV-IMPL)
PANE_ROLE="IMPL"
PROMPT="%F{green}[IMPL]%f %~ %# " ;;
DEV-PROMPT)
PANE_ROLE="PROMPT"
PROMPT="%F{cyan}[PROMPT]%f %~ %# " ;;
DEV-PLAN)
PANE_ROLE="PLAN"
PROMPT="%F{yellow}[PLAN]%f %~ %# " ;;
esac
if [[ -n "$PANE_ROLE" ]]; then
echo -ne "\033]0;${PANE_ROLE}\007"
_pane_title_precmd() {
echo -ne "\033]0;${PANE_ROLE}\007"
}
precmd_functions+=(_pane_title_precmd)
fi
# ── Claude Code launch alias (role-aware) ──
# Type "cc" to launch with the right flags.
case "$ITERM_PROFILE" in
DEV-AUDIT) alias cc='claude --model opus --effort high --permission-mode plan' ;;
DEV-IMPL) alias cc='claude --model sonnet --effort high --permission-mode acceptEdits' ;;
DEV-PROMPT) alias cc='claude --model sonnet --effort medium' ;;
DEV-PLAN) alias cc='claude --model sonnet --effort low' ;;
esac
Then run source ~/.zshrc in each pane to apply.
Why this works reliably
- $ITERM_PROFILE is set automatically by iTerm2 on every session — including arrangement restores. No dependency on startup commands.
- precmd_functions+=() adds to the hook array rather than overwriting it, so existing hooks from pyenv, fnm, conda, etc. are preserved.
- Normal terminals (Default profile) are completely unaffected.
05
Window Layout & Arrangement
Create a 2×2 pane layout, save it, and configure iTerm2 to restore it automatically on launch.
Target layout
AUDIT
adversarial review
opus · high · plan
PROMPT
prompt engineering
sonnet · medium
IMPL
code writing
sonnet · high · acceptEdits
PLAN
architecture & docs
sonnet · low
5.1
Create the 2×2 split
- Open a new window with the DEV-AUDIT profile.
- ⌘D — split right. Right-click the new pane → Edit Session → change profile to DEV-PROMPT.
- Click back on the left pane (AUDIT). ⌘⇧D — split down. Change the new pane to DEV-IMPL.
- Click on the top-right pane (PROMPT). ⌘⇧D — split down. Change the new pane to DEV-PLAN.
Final result — 4 panes with coloured prompts, badges, and distinct background tints
5.2
Save as default arrangement
- Window → Arrangements → Save Window Arrangement — give it a name (e.g. your project name).
- Go to iTerm2 → Settings → General → Startup and set "Window restoration policy" to "Open Default Window Arrangement".
- 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"
Result: Every time you open iTerm2, your 4-pane layout restores automatically with the correct profiles, directories, coloured prompts, and badges. No manual setup needed.
06
Launch Claude Code
Type cc in any pane. The alias you set up in Step 4 launches Claude Code with the correct model, effort level, and permissions for that pane.
| Pane | cc expands to | What you see |
|---|---|---|
| AUDIT | claude --model opus --effort high --permission-mode plan | Opus · plan mode on |
| IMPL | claude --model sonnet --effort high --permission-mode acceptEdits | Sonnet · accept edits on |
| PROMPT | claude --model sonnet --effort medium | Sonnet · medium effort |
| PLAN | claude --model sonnet --effort low | Sonnet · low effort |
All 4 panes with Claude Code running — Opus in AUDIT (plan mode), Sonnet in the rest
Override anytime: The cc alias is a convenience, not a lock-in. You can always type the full command with different flags when you need to (e.g. claude --model opus --effort max).
Note: On some systems, cc is aliased to the C compiler. If you work with C/C++, rename the alias to cl or claude-go in your ~/.zshrc.
Note: On some systems, cc is aliased to the C compiler. If you work with C/C++, rename the alias to cl or claude-go in your ~/.zshrc.
Ref
CLI flags reference
| Flag | Purpose |
|---|---|
| --model opus|sonnet|haiku | Model selection (or full IDs like claude-opus-4-6) |
| --effort low|medium|high|max | How much thinking effort Claude uses |
| --permission-mode plan | Read-only — Claude cannot write files |
| --permission-mode acceptEdits | Auto-accept file edits without prompting |
| --append-system-prompt "..." | Add custom instructions on top of defaults |
| --continue | Resume most recent conversation in this directory |
| --resume | Resume a specific session by ID |
Version note: Flags verified against Claude Code v2.1.72 (March 2026). CLI tools update frequently — run claude --help if a flag isn't recognised.
07
Keyboard Shortcuts
iTerm2 navigation
⌘⌥←/→
Switch panes (left/right)
⌘⌥↑/↓
Switch panes (up/down)
⌘D
Split right
⌘⇧D
Split down
⌘⇧⏎
Zoom current pane (toggle)
⌘M
Set mark (bookmark position)
⌘⇧↑
Jump to previous mark
⌘K
Clear terminal buffer
Claude Code (inside a session)
Esc
Interrupt generation
CtrlC
Cancel, return to prompt
/clear
Reset conversation context
/compact
Compress context (keeps summary)
/model
Switch model mid-session
/effort
Switch effort mid-session
08
Workflow & Tips
↺
The change cycle
Every code change follows this pattern across panes:
PLAN → Discuss approach. No file writes. Get design sign-off.
IMPL → Implement. Run tests (must pass before proceeding).
AUDIT → Review changed files (read-only). Feed findings to IMPL.
PROMPT → Prompt/content changes (always separate from code).
⚡
Cross-pane handoff
When AUDIT finds an issue, copy its output and paste into IMPL:
"The AUDIT pane identified: [paste findings].
Fix this while preserving existing patterns.
Do not touch unrelated files."
💡
Keep context clean
- 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.
The golden rule: When a conversation goes stale — Claude starts repeating itself or loses track of files — type /clear and start fresh with a tightly-scoped prompt. Short, focused sessions always beat long sprawling ones.
09
Daily Playbook
AM
Start of session
# 1. Open iTerm2 (arrangement auto-restores)
# 2. Type "cc" in each pane
# 3. PLAN — review where you left off
git log --oneline -10
# 4. IMPL — quick smoke test
pytest tests/ -x --tb=short
PM
End of session
# 1. IMPL — run full test suite
pytest tests/ -v --tb=short
# 2. IMPL — stage and commit
git add -p
git commit -m "feat: ..."
# 3. Compress long contexts instead of clearing
# Type /compact inside Claude Code
# 4. Save arrangement if layout changed
# Window → Arrangements → Save Window Arrangement
10
Adapt for Other Projects
This setup is project-agnostic. To use it with a different codebase:
1
Create new profiles (or duplicate existing ones)
Use a project-specific prefix: SS-AUDIT, SS-IMPL, etc. for a project called SensiSpend. Or keep DEV-* and just change the directory.
2
Update Initial Directory in each profile
Point to the new project path in each profile's General tab.
3
Add case entries to ~/.zshrc (if using new profile names)
Add matching entries in both case blocks for the new names:
# Example for a project called SensiSpend
SS-AUDIT)
PANE_ROLE="AUDIT"
PROMPT="%F{magenta}[AUDIT]%f %~ %# " ;;
# ... same pattern for SS-IMPL, SS-PROMPT, SS-PLAN
4
Save a new window arrangement
Name it after the project so you can switch between layouts for different projects.