The Complete Claude Guide
← Back to topic
Chapter 19 · CLI

Parallelism: worktrees, background tasks and agent view

Parallel work advances several tasks at once: worktrees give separate working copies of the repo, background tasks run in the background, and agent view centralizes managing multiple agents.

Verified against source on 2026-09-30

Video

Keep parallel edits apart

You will use separate worktrees, verify the starting revision, review changes and preserve work before cleanup. Outputs are illustrations.

Worktree and agent-view sources checked September 30, 2026 describe file-edit separation, not complete service isolation. Worktrees share repository history and remote; saved permission approvals and project plugins can also be shared.

Split by independent outcome

Give one worker typography and another quiz behavior only if the files and acceptance checks are separable. Two workers editing the same HTML still create integration work even in separate directories.

Plan two independent practice tasks: typography and quiz keyboard behavior.
State files, starting revision, tests and owner of integration for each.
Do not start sessions, edit, commit, push or open a PR yet.

A sequential workflow is better when the second task depends on the first.

Verify the base before a session

From a disposable Git repository, inspect:

git status --short
git rev-parse HEAD
git worktree list

Current Claude defaults can start a new worktree from the repository's default branch rather than your current feature HEAD. Check actual base and worktree.baseRef before assuming unpushed changes are included. A clean new directory does not prove the right version.

Optional isolated practice

To start a named Claude session in a worktree:

claude --worktree course-type

Inspect its actual directory and revision before editing. Do not use .worktreeinclude to copy secrets simply because documentation offers that feature. Use synthetic files and the minimum dependencies needed for the task.

Change typography in the practice page only after confirming this worktree's base.
Keep text and quiz logic unchanged. Do not push, open a PR or deploy.
Return the diff, test results and worktree path.

Illustrative handoff:

Worktree: [actual path]
Base: [actual revision]
Changed: [actual files]
Checks: [executed results]
Not done: push, PR, deployment
Background sessions have different effects

Agent view manages multiple local sessions and jobs. Current docs say a background session that isolates its code changes can commit, push its branch and open a draft PR without asking unless you tell it not to. That is a material difference from a harmless local preview. Put “no push, no PR” in practice instructions and inspect actual configuration.

Isolation can be skipped outside Git, for writes outside the working directory or when already in a linked worktree. Do not let the interface's “background” label stand in for checking the directory. A shared remote service remains shared even with isolated files.

Integrate and clean up deliberately

Review each diff against the verified base and run the combined checks after integrating. Do not assume two passing branches pass together.

Inspect changed/untracked files and unpushed commits before removing a worktree. Current agent-view deletion routes differ: some delete uncommitted work; shell removal may retain it. Keep needed work first. Do not use force removal to tidy a directory whose contents you have not checked.

Graded practice

Easy: independence

Split a task by files and checks. Success: integration has one owner.

Intermediate: correct base

Compare main and worktree revisions. Success: explain any difference.

Challenging: combined result

Review both proposed changes together. Success: combined keyboard and layout checks pass before cleanup.

Troubleshooting

Missing file: verify tracked files/base, not just directory name.

Unexpected PR: inspect background-session behavior and stop remote effects.

Changes collide: narrow ownership or work sequentially.

Worktree kept: inspect unpushed/untracked work instead of force-deleting.

Permission persisted: review shared local settings after the exercise.

Mechanism animation (illustration)

Filmed demo · Video is added in the media phase

Recap

Comprehension check

What problem do worktrees solve?

Recap

Sources and further reading

← Previous Back to topic Next →