Running Claude Code subagents in parallel: claude agents, --worktree, --tmux

Explained via the real output of the background-agent management command.

What "parallel" means here

Running multiple sessions (main + background agents, or several terminals) at once, each on an independent task, so total wall-clock time drops versus doing everything serially in one session.

See what's running: claude agents

`claude agents --json` prints active sessions in a script-readable form. A real run on this Mac returned:

$ claude agents --json
[
  {
    "pid": 87933,
    "cwd": "/Users/you/project",
    "kind": "interactive",
    "startedAt": 1785220534793,
    "sessionId": "52989523-4d95-49b6-bc11-4ce04f49e0b6",
    "name": "my-session"
  }
]

Parallel branches with --worktree

`-w, --worktree [name]` starts a session in a new git worktree — isolated from your main tree, good for "feature in one, bugfix in the other" style parallel work.

Pairing with tmux

`--tmux` creates a tmux session for the worktree (using native iTerm2 panes when available; `--tmux=classic` forces traditional tmux).

Starting in the background

`--bg, --background` starts a session and returns control immediately; manage it via `claude agents`.

Watch out for

Multiple sessions editing the same files can conflict. Split by directory/feature ownership, and protect critical changes with permissions or a PreToolUse hook.

FAQ

How do I see running sessions?

`claude agents --json` returns pid, cwd, sessionId and more.

How do I work on branches in parallel?

Use `--worktree` to start a session in a new git worktree.

Can I use tmux with it?

Yes — `--tmux` (or `--tmux=classic`) creates a tmux session for the worktree.

What should I watch for?

File conflicts across sessions — split ownership and protect critical changes with permissions/hooks.

Find configs for parallel workflows →Learn systematically at School →See the All-Access plan →