Skip to content
Shell
2.7 KB
Raw Blame

iTerm2 Setup for Claude Code Parallel Sessions

Follow this guide to set up iTerm2 for optimal parallel Claude sessions.

1. Enable System Notifications

Step 1: iTerm2 Preferences

  1. Open iTerm2
  2. Press Cmd + , to open Preferences
  3. Go to: Profiles > Terminal
  4. Check: "Send Notification Center alerts"

Step 2: macOS Notification Settings

  1. Open System Settings > Notifications
  2. Find iTerm2
  3. Enable: Allow Notifications
  4. Set style to: Alerts (not Banners - you want them to stay)

2. Set Up Numbered Tabs

Create a Profile for Claude Sessions

  1. iTerm2 Preferences > Profiles
  2. Click + to add new profile
  3. Name it: "Claude Session"
  4. Under General: Set Badge to show session number
  5. Under Colors: Choose a distinct color scheme
  6. Under Terminal: Check "Send Notification Center alerts"

Create 5 Default Tabs

  1. Open 5 tabs (Cmd + T four times)
  2. Right-click each tab > Edit Tab Title:
    • Tab 1: "Claude 1"
    • Tab 2: "Claude 2"
    • Tab 3: "Claude 3"
    • Tab 4: "Claude 4"
    • Tab 5: "Claude 5"
  3. Window > Save Window Arrangement
  4. Name it: "Claude Workspace"

Auto-Launch Arrangement

  1. Preferences > General > Startup
  2. Set: "Open Default Window Arrangement"
  3. Preferences > Arrangements
  4. Set "Claude Workspace" as default

3. Shell Aliases

Add these to your ~/.zshrc for quick access:

# Teleport shortcut
alias ct='claude --teleport'

# Quick numbered session launchers
alias c1='echo "Starting Claude 1..."'
alias c2='echo "Starting Claude 2..."'

4. Keyboard Shortcuts

These are usually default in iTerm2:

Shortcut Action
Cmd + 1 Select Tab 1
Cmd + 2 Select Tab 2
Cmd + 3 Select Tab 3
Cmd + 4 Select Tab 4
Cmd + 5 Select Tab 5
Cmd + T New Tab

5. Visual Differentiation

Tab Colors

In each tab:

  1. Right-click tab
  2. "Edit Session"
  3. Under "Colors", set a unique tab color per session

6. Daily Workflow

Morning Startup

  1. Open your Claude Workspace arrangement
  2. Tab 1: Main development work
  3. Tab 2: Tests/verification
  4. Tab 3-5: Ready for parallel tasks

During the Day

  1. Poll tabs every 10-15 minutes
  2. Watch for notifications - Claude waiting for input
  3. Farm out long tasks with ampersand suffix
  4. Check claude.ai/code for cloud session status

7. Key Commands

Command Purpose
claude "task" Start interactive session
claude "task" & Send to cloud, free terminal
claude --teleport Pull cloud session back
claude --resume Resume last local session

Verification

Open System Settings > Notifications > iTerm2 and confirm:

  • Allow Notifications: ON
  • Alert style: Alerts

You should now receive notifications when Claude needs your input across any tab.