CourseGuidesArticlesPodcastGitHubAboutStart free course
Course/Automation for Power Users

8 min · +140 XP

Several sessions at once

Worktrees, background sessions and agent view, and when parallel work pays off.

By the end of this lesson

You will be able to run several Claude Code sessions without them overwriting each other, find them again, and judge when parallel work is worth its cost.

One Claude Code session works on one thing at a time. When you have several independent tasks, such as a bug fix, a review and a test investigation, you can run several sessions side by side. The main risk is two sessions editing the same files, and git worktrees remove that risk.

A git worktree is a separate working folder with its own files and branch that shares the repository's history with your main checkout. Each session in its own worktree edits its own copy, so one can build a feature while another fixes a bug.

Worktrees

💬 From inside a session

“Do this task in a separate git worktree so my main folder stays untouched: add CSV export to the reports page. Install what the worktree needs, run the tests there, and tell me the branch name when you are done.”

Claude creates the worktree itself. The command below starts a whole session in one from the terminal.

Start a session in its own worktree
claude --worktree feature-auth

Creates .claude/worktrees/feature-auth/ at the repository root on a new branch worktree-feature-auth and starts Claude there. Run it with another name in a second terminal for a second isolated session; without a name, Claude picks one.

Worktree housekeeping

  1. 1Add .claude/worktrees/ to .gitignore so worktree files do not show up as untracked in the main checkout; ask Claude to do it together with the next step.
  2. 2A worktree is a fresh checkout: install dependencies there, or ask Claude to. A .worktreeinclude file copies gitignored files such as .env into new worktrees: "create a .worktreeinclude that copies .env into new worktrees".
  3. 3Run claude once in the folder first: an interactive --worktree run needs the folder to be trusted.
  4. 4Inside a session you can also say "work in a worktree", and Claude creates one.

Background sessions and agent view

Send a task to the background
claude --bg --name "flaky-test-fix" "investigate the flaky SettingsChangeDetector test"

The session starts in the background and your terminal is free at once. Claude Code prints the short id and the commands: claude agents lists sessions, claude attach <id> opens one here, claude logs <id> shows recent output, claude stop <id> stops it. The prompt is a normal argument; --bg cannot be combined with -p.

Agent view: claude agents

  1. 1Run claude agents. Sessions are grouped as needing input, working and completed.
  2. 2Type a task in the input at the bottom and press Enter. Every prompt there starts a new background session.
  3. 3Select a row and press Space to peek at its latest output or question, and reply without leaving the table.
  4. 4Press Enter or → to attach to the full conversation; ← on an empty prompt detaches again.
  5. 5In a normal session, /bg or ← on an empty prompt moves it to the background.
  6. 6Before editing files, a background session moves into its own git worktree, so parallel sessions do not write to the same copy.
ℹResearch preview

Agent view is in research preview, so its screens and keys may change. Background sessions run on your machine: they survive sleep but stop if the computer shuts down. Deleting a session in agent view also deletes the worktree Claude created for it, so commit first.

Names and resuming

Find your way back

  1. 1claude -n "auth-refactor" starts a session with a name; /rename changes it during the session.
  2. 2claude --resume auth-refactor resumes a named session; claude --resume alone opens a picker.
  3. 3claude --continue reopens the most recent session in the current folder; /resume switches from inside a session.

When parallel helps

Worth it, and not

  1. 1Worth it: tasks that do not depend on each other and touch different files.
  2. 2Worth it: long jobs you would otherwise wait for, such as a test investigation while you work on something else.
  3. 3Not worth it: steps that build on each other. One session with a plan does that better.
  4. 4Not worth it on a tight plan: each session uses your quota on its own, so ten agents use it about ten times as fast. Look at /usage before dispatching many.
  5. 5Every result still needs your review. Three finished branches need three reviews.
Quick check

Two sessions must change different parts of one repository at the same time. What keeps them from overwriting each other's files?

Quick check

You are on a Pro plan and want to dispatch ten background sessions to try ten ideas. What should you expect?

Facts checked against the official Claude Code docs October 24, 2026 · source

EAEvgenii Arsentev

Author

Evgenii Arsentev

PhD · Chief Executive Officer, digital health