Skip to content
Shell
5.0 KB
Raw Blame

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:

  1. Open Claude app on iPhone/iPad
  2. Start a coding session
  3. It runs with full tool access in the cloud
  4. Later, --teleport to 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:

  1. Open iTerm2 Preferences (Cmd + ,)
  2. Go to: Profiles → Terminal
  3. Enable: "Post notifications for terminal bells"
  4. 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):

  1. Open Claude app
  2. "Review the open PRs and summarize what needs attention"
  3. 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:

  1. Kick off tasks in each terminal
  2. Poll regularly - check each tab for prompts
  3. Respond to notifications - iTerm will alert you
  4. Farm out long tasks with &
  5. Pull back with --teleport when 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.