Parallel Sessions & Teleport Guide
This guide documents the workflow patterns Boris Cherny (creator of Claude Code) uses to run 15+ Claude sessions simultaneously.
The Pattern: Breadth Over Depth
Instead of using one Claude session sequentially, treat Claude like a team of developers:
- Session 1: Working on feature A
- Session 2: Writing tests for feature B
- Session 3: Fixing bug C
- Session 4: Updating docs
- Session 5: Researching approach for feature D
Key Features You Need to Know
1. The & Suffix (Background to Web)
Add & at the end of your prompt to hand off the session to claude.ai/code:
claude "Refactor the authentication module to use JWTs" &
This:
- Starts the task locally
- Uploads the session to cloud
- Frees up your terminal immediately
- You can check progress at https://claude.ai/code
Use Case: Long-running tasks you don't need to monitor actively.
2. The --teleport Flag (Pull Session Back)
Bring a web session back to your terminal:
claude --teleport
This:
- Lists your active cloud sessions
- Lets you select one to continue locally
- Preserves full context from the web session
Use Case:
- Started a session on your phone, want to continue on desktop
- Web session finished, want to continue locally with the results
3. Session Continuation from iOS
The Claude iOS app supports Claude Code sessions:
- Open Claude app on iPhone/iPad
- Start a coding session
- It runs with full tool access in the cloud
- Later,
--teleportto bring it to your Mac
Use Case: Start tasks during commute, continue at desk.
4. Web Sessions at claude.ai/code
Go to https://claude.ai/code to:
- View all active sessions
- Start new sessions without terminal
- Monitor long-running tasks
- Share session URLs with teammates
Terminal Setup for Parallel Work
Numbered Tabs (Boris's Pattern)
Set up 5 terminal tabs numbered 1-5:
iTerm2:
- Right-click tab → Edit Tab Title
- Name them: "Claude 1", "Claude 2", etc.
- Or use badges: View → Show Tab Bar, then number them
Terminal.app:
- Shell → Edit Tab Title
iTerm2 Notifications (Essential)
Get notified when Claude needs your input:
- Open iTerm2 Preferences (Cmd + ,)
- Go to: Profiles → Terminal
- Enable: "Post notifications for terminal bells"
- Add to your shell profile (~/.zshrc):
# Notify when command completes
export PROMPT_COMMAND='echo -ne "\a"'
Or use the simpler approach - add to Claude config:
{
"notifications": {
"onWaitingForInput": true
}
}
Workflow Examples
Example 1: Feature Development
# Terminal 1 - Main feature work
claude "Implement user profile page"
# Terminal 2 - Tests (in parallel)
claude "Write tests for the user service"
# Terminal 3 - Related refactor
claude "Clean up the auth middleware" & # Send to cloud
# Check Terminal 3 progress later at claude.ai/code
Example 2: Morning Phone → Desktop
On iPhone (during commute):
- Open Claude app
- "Review the open PRs and summarize what needs attention"
- Claude researches and writes summary
At Desktop:
claude --teleport
# Select the phone session
# Continue: "Let's address the first PR..."
Example 3: Long-Running Task
# Start big refactor
claude "Refactor entire API layer to use new error handling" &
# Continue other work in new terminal
claude "Fix the login bug reported in issue #42"
# Check refactor progress at claude.ai/code
# When done, teleport back if needed
Polling Pattern
With 5 terminals running:
- Kick off tasks in each terminal
- Poll regularly - check each tab for prompts
- Respond to notifications - iTerm will alert you
- Farm out long tasks with
& - Pull back with
--teleportwhen needed
Commands Quick Reference
| Command | What It Does |
|---|---|
claude "task" |
Start interactive session |
claude "task" & |
Start and send to cloud |
claude --teleport |
Pull cloud session to terminal |
claude --resume |
Resume last local session |
claude -p "task" |
Non-interactive (print and exit) |
Best Practices
DO:
- Number your terminal tabs for quick switching
- Enable notifications so you don't miss prompts
- Use
&for any task that might take >5 minutes - Start research tasks from phone during downtime
- Keep one terminal free for quick tasks
DON'T:
- Wait for one session to complete before starting another
- Run all sessions locally (use cloud for long tasks)
- Ignore notifications (Claude might be blocked waiting)
- Forget about background sessions (check claude.ai/code regularly)
Mental Model
Think of it as:
You (Manager)
├── Claude 1 (Terminal) - Active conversation
├── Claude 2 (Terminal) - Active conversation
├── Claude 3 (Cloud via &) - Working independently
├── Claude 4 (Cloud via &) - Working independently
└── Claude 5 (Phone) - Mobile session, will teleport later
You're orchestrating a team, not having a single conversation.