Learning objectives

By the end of this chapter, you will be able to:

1. Explain that Claude Code lives inside the Claude desktop app (the **Code** tab) as a graphical front end to the same engine and configuration the CLI uses — the same `CLAUDE.md`, MCP servers, and hooks — and describe what 'background agents' / cloud sessions are.
2. Distinguish the two operating modes: **Local worktree** mode (everything runs on your machine; Claude Code creates Git worktrees locally) versus **cloud** mode (managed, containerized Claude Code instances run on Anthropic's infrastructure, clone your repo via GitHub, work, commit, and open pull requests), and know the current surface naming (a Local / Remote / SSH environment picker; 'cloud' or 'background' sessions) and what differs between them (where code runs, repo access, available tools, MCP).
3. Explain Git worktrees in Claude Code — one repository checked out into several independent directories so multiple agents work on separate branches without colliding — and the lifecycle (Claude creates a worktree on a new branch → all work happens in that directory → a commit lands on the worktree's branch, leaving the original branch untouched → you merge when satisfied), plus the current defaults a 2025 book may not state (worktrees branch from `origin/HEAD` by default; cleanup is conditional, not automatic).
4. Orchestrate parallel local and cloud agents — run several independent features at once across local sessions and a cloud background agent, each on its own branch — and recognize the load-bearing failure mode the chapter demonstrates: an agent that starts from the wrong branch (e.g. `main` instead of the feature branch) corrupts the later merge, so the correct starting branch must be specified and verified per agent.
5. Merge parallel feature branches safely — consolidate independently-developed branches through a temporary integration branch, resolve conflicts, and **test the merged result locally before pushing** to the target branch — and understand that Claude Code has no magic 'merge all branches' command: it runs standard Git in a worktree, and in this delegated local-merge workflow a human approves the conflict resolution and the push (whereas a *pull request* can be set to fix and merge itself via Desktop Auto-fix / Auto-merge when you enable them and GitHub allows it).
6. Judge when running agents in parallel is counterproductive — tightly coupled features, shared state / ordering constraints, very small tasks, high coordination cost, and exploratory or uncertain work — and apply the parallel-development checklist (independent files per task; verify each agent's starting branch; test the merge before pushing; clean up worktrees afterward).

Before we start — desktop app, "local vs cloud," branches, worktrees, and merging

Skim this if you're already comfortable with Git branches, what a pull request is, and the idea of running more than one Claude Code agent at once (Chapters 5–7). If any of that is fuzzy, read it first — this chapter assembles all of those pieces into a single workflow.

The Claude desktop app vs the terminal. Until now you've mostly driven Claude Code from a terminal by typing claude. There is also a Claude desktop application (a normal Mac/Windows app) — and Claude Code lives inside it, on a tab called Code, with a graphical interface (buttons, panels, diffs) instead of a text prompt. It is the same Claude Code underneath: the same engine, and the same configuration — your CLAUDE.md, your MCP servers, your hooks all still apply. The desktop app is a front end, not a different product.

"Local" vs "cloud." This is the chapter's central distinction. Local means Claude Code runs on your machine, edits files on your disk, and uses your installed tools — exactly like the terminal. Cloud means Anthropic spins up a Claude Code instance on their own servers (in an isolated sandbox), which clones your repository from GitHub, does the work there, commits, and can open a pull request — all without using your machine. A cloud instance that runs on its own like this is often called a background agent or a cloud session: you start it, it works on its own, and you check back later.

A branch (recap). A Git branch is an independent line of changes in a repository. You can have many branches; each can move forward on its own, and you later merge one into another to combine the work. The book's project keeps its in-progress feature work on a branch called project/hookhub.

A worktree. This is the mechanical trick that makes everything else possible, and §3 explains it in full. The one-line version: a Git worktree lets you check out several branches at once, each into its own separate folder, all backed by the same single repository. So three agents can each work in their own folder on their own branch — no stashing, no switching, no stepping on each other.

Merging, and a pull request (recap from Chapter 5). Merging combines the commits from one branch into another. A pull request (PR) is GitHub's "please review and merge these changes" proposal — a place to see the diff, comment, and approve. In this chapter the cloud and mobile agents open PRs; a human reviews and merges them.

Parallel / orchestration. Running more than one agent at the same time is parallel work; deciding what each does, on which branch, and how their outputs come back together is orchestration. Chapter 6 ran parallel agents in separate terminals; Chapter 7 delegated to in-session subagents. This chapter does it the way the desktop app makes easy: several worktree-isolated agents, some local and some in the cloud, then a coordinated merge.

How to read this chapter. Each numbered section ends with an > Analogy — … box that restates the idea in plain language. Lean on them or skim them as you like.

Why this chapter matters

Everything up to here has, fundamentally, been one Claude Code working on one thing while you watch. That's the right default, and it's most of the value. But it has a ceiling: you, the human, are the bottleneck — one task in flight, your machine, your attention. This chapter is about lifting that ceiling without losing control of the codebase.

The move is from sequential development (do feature A, then B, then C) to orchestrated, parallel development (A, B, and C at once, each isolated, then merged). Three things make that safe rather than chaotic. First, the desktop app gives parallel sessions a real interface — a sidebar of running agents, diff viewers, the ability to send work to the cloud — instead of a wall of terminal tabs. Second, Git worktrees give each agent its own directory and branch, so concurrent edits physically cannot collide. Third, the cloud lets some of that work run off your machine entirely, including from your phone, so "I kicked off the redesign" no longer means "my laptop is busy for an hour."

The honest counterweight — which the chapter is unusually good about, and which we'll treat as a first-class section — is that parallelism is not free and not always wise. Every agent carries setup overhead, and the moment two agents touch the same file or one depends on another's output, you've traded saved time for merge conflicts and coordination cost. The skill this chapter builds is therefore two-sided: how to run agents in parallel, and how to recognize the tasks where you shouldn't.

A note on currency. This is the fastest-moving surface in the book. The desktop app, the cloud/web experience, and the mobile paths were all redesigned and expanded through 2025–2026, so exact tab names, menu labels, environment-picker wording, and worktree storage paths drift between releases. Throughout, we teach the stable concepts (local vs cloud; worktree isolation; integration-branch merging) as load-bearing, and soft-word the surface details — verify the exact current UI against code.claude.com/docs/en/desktop and …/worktrees on your install. Where the book's 2025 wording has already moved, the lesson flags it inline and the source ledger records it.

Lesson

1. Claude Code on the desktop — one engine, a graphical front end

The first idea is small but reframes the rest: Claude Code is not only a terminal program. Anthropic integrated it into the Claude desktop application, where it appears as a Code tab — a graphical Claude Code with the same brain as the CLI. It shares the underlying engine and, crucially, the same project configuration: the CLAUDE.md you wrote in Chapter 2, the MCP servers from Chapter 4, the hooks from Chapter 3 all carry over. You're not learning a new tool; you're getting a new surface on the tool you know.

To start, you pick a workspace folder — almost always a Git repository (ideally one connected to GitHub, which matters for cloud mode in §2). That folder becomes the place Claude Code operates. From there the desktop app looks like a chat box over your repo: a prompt ("Find a small task in the codebase and do it"), a model selector, and suggestion cards ("Create or update my CLAUDE.md file", "Search for a TODO comment and fix it"). The graphical surface is the point — diffs to approve, panels to watch, sessions side by side — but underneath, each action is the same Claude Code agent you've been using.

The deeper reason the desktop app exists is the rest of this chapter: it's built to run many agents at once. A redesign of the desktop app explicitly oriented it around parallel work — a sidebar listing every running session (filterable by status, project, and environment), an integrated diff viewer, and the ability to launch and watch several agents together. And it's the launch point for background agents — Claude Code instances that run on their own (locally or in the cloud) while you do something else, which §2 unpacks.

A drift note, stated once. A 2025 book describes the desktop surface as it was then. As of writing, the desktop app organizes work into more than one tab (a chat surface, a longer-running-work surface, and the Code tab we care about), and starting a session involves an explicit environment picker (Local / Remote / SSH) rather than a single local/cloud toggle. The concepts below are stable; treat exact tab and menu names as things to confirm in code.claude.com/docs/en/desktop.

Analogy — the same car, now with a dashboard The terminal claude is a car you drive by feel — fast and precise once you know it, but everything is bare controls. The desktop Code tab is the same car with a proper dashboard: gauges, a reversing camera, buttons for the things you used to do by memory. The engine, the fuel, the route settings (CLAUDE.md, MCP, hooks) are identical — you've just swapped a stick-and-pedals cockpit for one where you can see three trips being planned at once.

2. Two places work can run — Local worktree vs cloud

Now the central distinction. When you start work in the desktop app, you choose where Claude Code actually runs.

Local worktree mode. Everything happens on your machine. Claude Code spins up Git worktrees locally (§3), edits files on your disk, and uses your local environment and tools. Nothing leaves your computer; nothing runs in the cloud. Because the work is local, Claude Code needs a folder to operate in — that's the workspace you picked in §1. This is the mode that behaves exactly like the terminal you already know, just with worktree isolation managed for you.

Cloud mode. Switch to the cloud option and Claude Code runs as managed, containerized instances on Anthropic's infrastructure instead of on your laptop. Those instances obviously can't see your local disk, so they need another way to reach your code: you grant access to your GitHub repositories. Once granted, a cloud instance behaves like any other developer on the project. The workflow, in order:

1. Anthropic spins up a Claude Code instance.
2. The instance clones the repository.
3. It works directly on the code.
4. It commits changes.
5. It can open a pull request.

Two consequences make cloud mode powerful. First, it doesn't use your machine — you can close the app and the work continues (and you can start it from your phone, §6). Second, it scales: you can run several cloud instances in parallel, each on a different task, with the number you can run at once depending on your plan. Cloud instances running on their own like this are the background agents the chapter keeps referring to.

What actually differs between the two modes is worth holding in your head, because it explains later behavior:

That config row is the important nuance — and a place the book's framing is too broad. A cloud session is not a blank, default-only environment: it starts from a fresh clone of your repository, so anything committed to the repo comes with it — your repo CLAUDE.md, the hooks in .claude/settings.json, the MCP servers declared in .mcp.json, your .claude/skills, .claude/agents, and .claude/commands, and plugins declared in .claude/settings.json. What doesn't follow the session is config that lives only on your machine: your user ~/.claude/CLAUDE.md, user-local skills/agents/commands, plugins enabled only in your user settings, and MCP servers you added with claude mcp add (those write to your local user config, not the repo). The fix is the same in every case — commit it to the repo (the docs also describe per-environment settings, a setup script, and a SessionStart hook for cloud-only setup). (The docs don't explicitly address output styles in cloud sessions, so don't assume either way.)

A drift note. The book's terms for cloud mode — "Claude Code web / remote workers / background agents" — are all in current use, but the surface has firmed up. As of writing the desktop environment picker offers Local / Remote / SSH (Remote being the cloud option), the browser experience lives at claude.ai/code ("Claude Code on the web," a research preview), and the docs lean on the terms cloud session and background session. The five-step clone→work→commit→PR flow is exactly right; verify the picker labels against code.claude.com/docs/en/desktop-quickstart.

Analogy — your own workshop vs a contractor's shop Local mode is doing the job at your own bench: your tools, your materials, your mess, and when you lock up for the night the job pauses. Cloud mode is handing the job to a contractor's shop across town: you ship them a crate (the cloned repo), and they build from whatever you packed in it — your committed guidelines, jigs, and tool list (repo config) are all right there. The only things missing are the tools that never left your home garage (config that lives only on your machine) — and the fix is simply to pack those in the crate too (commit them). They keep going after you've gone home, calling you to approve the result (a PR). Neither is "better" — one keeps everything under your hands, the other frees your bench.

3. Git worktrees — many branches checked out at once

Local mode leans entirely on Git worktrees, so it's worth understanding properly. Normally a Git repository has one working directory, and to switch branches you check one out in place — which means you can only have one branch's files on disk at a time, and switching forces you to stash or commit whatever you're in the middle of. A worktree removes that limit: it lets you check out multiple branches simultaneously, each into its own directory, all sharing the same underlying repository (no re-cloning). Two agents, two folders, two branches, zero collisions.

That's exactly what parallel agents need. Each agent gets its own branch in its own worktree directory, so there's no stashing, no branch-switching dance, and no risk of one agent's half-finished edit clobbering another's — the isolation is handled by the filesystem itself.

The lifecycle Claude Code follows inside a worktree is the mental model to memorize:

1. Claude Code creates a worktree on a new branch. (In the desktop app these get auto-generated friendly names like vigilant-fiestel or zealous-jemison; from the CLI you name them yourself.)
2. All code and changes happen inside that worktree's directory.
3. When Claude commits, the commit lands on the worktree's branch — not on your original branch.
4. The original branch (e.g. project/hookhub) stays completely untouched.
5. If you like what was built, you merge it in (§5).

So when you have two worktrees — say vigilant-fiestel and zealous-jemison — your editor shows the normal repo directory plus two extra directories, each a full copy of the code on its own branch. The folders look alike, but the branches are independent: a commit in one never appears in the other, or in project/hookhub, until you merge. That separation is the whole point — it's what lets multiple Claude instances each work on a totally fresh copy in a totally different branch.

A few current defaults a 2025 book won't state, worth knowing before you rely on worktrees:

• From the CLI, claude --worktree <name> creates a worktree (as of writing, at .claude/worktrees/<name>/ on a branch named worktree-<name>). The desktop app creates a worktree per session automatically and manages where it lives — so the exact storage path differs between the CLI and the app, and across versions. Add the worktree directory to .gitignore so its contents don't show up as untracked files.
• Base branch: as of writing, worktrees branch from origin/HEAD (your repository's remote default) by default, not your local HEAD — so a fresh worktree starts clean and may not contain your local unpushed commits. You can opt into branching from local HEAD with the worktree.baseRef: "head" setting. (This is a local-worktree default — it governs where a --worktree branch starts. A cloud session's starting point is a separate mechanism, a fresh clone of the selected repo/branch, not governed by worktree.baseRef; §4 shows why you verify the branch in either case.)
• Cleanup is conditional, not automatic. A clean, unnamed session with no changes is removed on exit; a named session, or one with uncommitted changes or new commits, prompts you to keep or remove it; non-interactive (-p) runs are not auto-removed. So "clean up your worktrees" (the checklist item in §7) is a real step, not something that always happens for free. Verify specifics at code.claude.com/docs/en/worktrees.

Analogy — separate workbenches, one shared stockroom Imagine a carpentry shop with one stockroom of timber (the repository) and several workbenches (worktrees). Each carpenter takes a copy of the plans to their own bench and builds there. Nobody has to clear the single bench to let the next person work, and a half-cut joint on one bench never lands on another. The stockroom is shared, so nothing is duplicated wastefully — but the work is fully separated until you decide to assemble the pieces into one finished cabinet (the merge).

4. Orchestrating parallel local and cloud agents

Now the pieces combine. The book's walkthrough runs three independent features at the same time on the HookHub demo app — two locally, one in the cloud — and the value is in watching how they stay isolated and where the sharp edge is.

The setup: the workspace points at the project repo, checked out to the project/hookhub branch, and the Next.js app is running locally (npm install, then npm run dev — it lands on port 3001 because 3000 is taken). Then three jobs are launched, deliberately chosen to be independent (different files, no dependency on each other's output):

1. A cloud research task — using the Claude app as a separate research environment, asked to find high-star GitHub repositories that implement Claude Code hooks. (Pure read/research; its output will later be pasted into the project.)
2. A local animation feature — a local Claude Code session adding UI animations, working in its own worktree (vigilant-fiestel).
3. A cloud hero redesign — a background agent in the cloud, told to redesign the hero section on the project/hookhub branch in an Anthropic style, on its own branch (claude/anthropic-hero-design-…).

At the peak, three processes run concurrently — two local, one in the cloud — each isolated. The local animation session finishes, proposes its diff, and you approve it; the research task returns its list of repositories, which you paste into a new local worktree session that adds them to the project's hooks.json. Three features, three branches, no collisions — because each lives in its own worktree (or cloud sandbox) on its own branch.

The teaching moment — verify the starting branch. Watch the cloud hero agent closely and you catch the chapter's most important lesson. The agent initially checks out main, not project/hookhub. That's wrong: the feature is meant to build on project/hookhub, and starting from main would create inconsistencies at merge time. The agent corrects itself —

git checkout origin/project/hookhub

— fetches the right code, and continues. But the point stands for you: an agent can start from the wrong base, and a wrong base silently poisons the later merge. Note the two distinct starting-point mechanisms at work, so you check the right thing: a cloud session begins from a fresh clone of the repo and whatever branch context it selected (which is what bit the hero agent here), while a local --worktree branches from origin/HEAD by default (§3) unless you set worktree.baseRef. Either way the discipline is the same — which is why the §7 checklist makes "verify the correct starting branch in each agent's prompt" a required step. Specify the branch explicitly, and check that each agent (local or cloud) is actually on it before you let it run.

By the end, three branches exist, each a feature developed in isolation: a remote branch from the cloud agent (the hero redesign) and two local worktree branches (animations, hooks-database). Consolidating them is §5.

A scale note (background, not Claude Code behavior). The "many agents at once" idea has a research lineage worth a sentence: Anthropic's account of its internal multi-agent research system describes an orchestrator-worker pattern — a lead agent coordinating specialized workers in parallel — and reports it beating a single agent on a research eval while using far more tokens (as reported, roughly an order of magnitude). The lesson there is the same one §7 makes operationally: parallelism buys speed and coverage on genuinely separable work, and costs when the work isn't separable. Treat those figures as reported background, not as Claude Code mechanics.

Analogy — a head chef running three stations A head chef doesn't cook a three-course meal one dish at a time. They fire the roast, the sauce, and the dessert stations at once, each cook at their own station with their own pans (worktrees), one of them prepping in a different kitchen entirely (the cloud). It works because the dishes are independent. But notice the chef's one non-negotiable check: "Are you starting from the right base?" A cook who reduces the wrong stock (checks out main) ruins the plating later — so the chef confirms each station's starting point before the heat goes on.

5. Merging parallel feature branches — integrate, test, then push

Three isolated branches are useless until they're one coherent codebase. This is the hard part of parallel work, and the chapter handles it with a pattern worth adopting wholesale: don't merge straight into your target branch — integrate on a throwaway branch, test, then push.

You can do this by hand, but the chapter delegates it to Claude Code with a plain instruction:

Merge all the commits here to branch project/hookhub

What Claude does next is the model to copy. Rather than merging each branch directly into project/hookhub, it works in a fresh worktree and creates a temporary integration branch — project/hookhub-merge — branched from the target. Then it merges each feature branch into that:

1. Resolve conflicts from the hero-redesign branch (the conflict is in the global CSS file — predictable, since a redesign and an animation pass both touch styling).
2. Merge the animations branch (vigilant-fiestel).
3. Merge the hooks-database branch (zealous-jemison).
4. Create the merge commit — but do not push yet.

The discipline is in step 4. Before pushing the integrated result into project/hookhub, you test it locally:

npm run dev

(In the book's run this surfaces a real wrinkle — the worktree's shell can't find npm until the environment is sourced, and dependencies need installing first with npm install — a reminder that a fresh worktree is a fresh environment.) The merged app comes up on port 3002, and you compare it against the original: the new Anthropic-style hero, the added repository entries, animations throughout — all three independently-built features coexisting correctly. Only after that validation do you approve the final push, merging project/hookhub-merge into project/hookhub. The result is three clean merge commits, one per feature.

The honest framing — there is no magic merge. Claude Code has no special "consolidate all branches" command. What happened above is standard Git — git checkout, git merge, conflict resolution, a test run — executed by an agent in a worktree because you delegated it. The agent is doing what a careful developer would do, and in the workflow taught here the human stays in the loop at the two moments that matter: approving the conflict resolution and approving the push — that is, this merge is advisory, not autonomous.

That human-in-the-loop is a property of this workflow, not a guarantee that every Claude Code merge is manual. Once you move to a pull request, the Desktop app's PR monitoring can automate more: as of writing it offers an Auto-fix toggle (Claude reads failing CI output and iterates to fix the checks) and an Auto-merge toggle (Claude merges the PR once all checks pass — squash merge — which requires auto-merge to be enabled in your GitHub repository settings). So the right mental model is: the local branch-consolidation you delegate stays under your approval, but a PR can be set up to fix and merge itself when you opt in and GitHub allows it. Verify the current toggles at code.claude.com/docs/en/desktop.

Analogy — a dress rehearsal before opening night Three departments built the set, the lighting, and the sound separately. You don't bolt each one straight onto the live stage on opening night — you assemble them on a rehearsal stage first (the integration branch), find the one place the lighting rig fouls the set (the CSS conflict), fix it there, and run a full dress rehearsal (test locally on :3002). Only when the rehearsal goes clean do you move it to the real stage (push to project/hookhub). The director signs off twice: on the fix, and on going live.

6. The same workflow from your phone — Claude Code in the cloud via mobile

The cloud mode of §2 has a striking consequence: if the work doesn't need your machine, it doesn't need you to be at a machine. Claude Code is integrated into the mobile app, and the same workflow runs from a phone — because all execution happens in the cloud. There's no local machine in the loop at all: the repository is cloned remotely, branches are checked out remotely, and changes are committed remotely.

The book's demo: from the phone, select the repo and instruct Claude to switch to project/hookhub and add an Anthropic-style footer. What follows mirrors the desktop cloud flow exactly — Claude fetches the repo, checks out the branch, inspects the project, identifies it as a Next.js app, writes a new Footer.tsx, wires it into page.tsx, commits, and opens a pull request. (Remember §2's nuance: a cloud session carries whatever is committed to the repo — its CLAUDE.md, .claude/settings.json hooks, .mcp.json servers, and .claude skills/agents/commands — but not config that lives only on your machine, such as servers added with claude mcp add. The book's repo here is a plain Next.js app with little committed config, so this session effectively runs with defaults.)

Back on GitHub, the PR shows the two changed files (page.tsx, Footer.tsx) and the footer integration in the diff. You can even tag Claude in the PR for a review:

@claude review this PR

— and in this demo the review stays manual: with no GitHub workflow configured on this branch (Chapter 5), no automated checks fire, so a human reviews and merges. (That's a property of this setup, not a rule — §5's note on Desktop Auto-fix / Auto-merge shows merges can be automated when you enable them and GitHub allows it.) To verify locally afterward, the loop is the familiar one:

git fetch
git pull
npm run dev

The takeaway the chapter lands on: the interface changes, the process doesn't. Phone, desktop, terminal — the engineering loop is identical: state intent, let Claude reason over the repo, review the output, iterate. The surface is just a window onto the same agent.

A drift note. "Mobile" is really two current paths, and a 2025 book may blur them. Claude Code on the web (claude.ai/code, a research preview) runs sessions entirely in the Anthropic cloud and is reachable from any browser including a phone — that's the all-cloud model the book demonstrates, plus an iOS app. Separately, Remote Control connects the Claude mobile app to a session running locally on your own machine (so your local files and config are reachable from the phone) — a different model the book doesn't cover. Verify the current shape at code.claude.com/docs/en/claude-code-on-the-web and …/remote-control.

Analogy — checking on the contractor from the road Because the contractor's shop (§2's cloud) works without you, you don't have to stand in it. You text the job from a traffic light — "switch to the project branch, add the footer" — and the shop clones the materials, builds the piece, and sends you a photo to approve (the PR). Nothing is happening in your garage; your phone is just a window into a shop across town. The work is identical to placing the order in person — you've just removed the requirement to be standing there.

7. When parallel agents are counterproductive

This is the section that makes the rest safe to use, and the book deserves credit for including it. Parallel agents are a tool, not a default. Reach for them on the wrong work and they cost you more than they save. The anti-patterns:

• Tightly coupled features. If two tasks modify the same files, or one needs the other's output to exist first, parallel agents produce merge conflicts or silently overwrite each other. If feature B needs feature A's interface, run them sequentially. (This is Chapter 6's independent-vs-dependent distinction, now with real stakes.)
• Shared state and ordering constraints. Database migrations, config-file edits, shared type definitions — these create implicit dependencies. Two agents appending to the same config, schema, or route file will collide, and resolving those conflicts often costs more than you saved.
• Small tasks. Every agent session has overhead: spinning up context, reading the codebase, planning. For a two-minute change, the setup dwarfs the work — just do it in one session.
• High coordination cost. If you find yourself writing long, painstakingly unambiguous specs just to keep agents from stepping on each other, that's the signal. The more effort you spend defining boundaries, the less you're gaining from parallelism.
• Exploratory or uncertain work. When you don't yet know the right approach — debugging a tricky bug, prototyping an unclear design — parallel agents just multiply the uncertainty. One focused session that iterates beats several agents chasing dead ends at once.

The mental model, stated plainly: parallel agents win when tasks are independent, well-scoped, and touch different parts of the codebase. When in doubt, start sequential and parallelize only once you've confirmed the tasks don't interact.

And the operational checklist the chapter closes on — your pre-flight before fanning out agents:

1. Independent files/components per task — confirm no two agents will edit the same files.
2. Verify the correct starting branch in each agent's prompt — the §4 lesson; a wrong base poisons the merge.
3. Test the merged result before pushing to the target branch — the §5 discipline.
4. Clean up worktree directories after merging — they don't all vanish on their own (§3).

Analogy — opening every lane at the supermarket More open checkout lanes clear a crowd faster — if shoppers are independent. But open ten lanes for a queue of three people and the idle cashiers cost more than they help (small tasks, overhead). Put a customer whose order depends on the person ahead of them — "ring me up after my friend pays" — in a separate lane and you get chaos, not speed (coupled tasks). And if you need a manager choreographing who stands where, the choreography is the bottleneck (coordination cost). Lanes are powerful; opening all of them for every queue is not.

The whole chapter in one image — the workshop with a satellite shop

Analogy — pedagogical summary, drawing on all seven sections

Run parallel development like a master carpenter with a workshop and a satellite shop across town, not like one person doing every job in sequence at a single bench.

A dashboard over the bench. The desktop Code tab is your old bench (the terminal) fitted with gauges and cameras — same engine, same materials (CLAUDE.md, MCP, hooks), now built to watch several jobs at once.

Two places to work. Some jobs you do at your own bench (local) with your full kit; others you hand to the satellite shop (cloud) — you give them keys to the materials store (GitHub access), they work in their own space with a standard kit, keep going after you've left, and call you to approve (a PR). You can place that order from the road (mobile).

Separate benches, one stockroom. Whoever works, they each take a copy of the plans to their own workbench (a worktree) — no clearing the single bench, no half-cut joint landing on someone else's work.

Fire the stations — but check the base. You run the roast, the sauce, and the dessert at once because they're independent — confirming first that nobody reduced the wrong stock (the wrong starting branch).

Dress rehearsal before opening night. You assemble the separate pieces on a rehearsal stage (an integration branch), fix the one place they foul each other, run a full dress rehearsal (test locally), and only then move to the live stage — signing off on the fix and on going live.

Don't open every lane for every queue. Parallelism is supermarket checkouts: more lanes clear a crowd, but opening all of them for three coupled shoppers is slower than one good lane. That's the chapter: parallel local and cloud agents, isolated by worktrees and reunited by a careful merge, are how you scale development throughput — when, and only when, the work is genuinely independent.

Activity — Split a real feature set into parallel and sequential work

Ten minutes, individual, no setup required. You'll practice the §4/§7 judgment — the discriminating skill this chapter builds — on work from your own world.

1. Pick a multi-part change you'd realistically give to a coding agent (e.g. "add dark mode, add a footer, add a search box, migrate the users table, rename an API field"). List 4–6 sub-tasks.
2. Mark each independent or dependent. For every pair that could run at once, ask: do they touch the same files? Does one need the other's output first? Is there shared state (a migration, a config, a shared type)? Tag each sub-task parallel-safe or must-be-sequential, and write the one reason.
3. Draft the per-agent prompts for the parallel-safe ones. For each, write the prompt you'd give its agent — and make sure it names (a) the starting branch and (b) which files it may and may not touch. (This is §7 checklist items 1–2, in your own words.)
4. Name the merge order. If you ran the parallel ones, in what order would you integrate them, and which pair is most likely to conflict? What's your test step before pushing? (§5.)
5. Spot the trap. Which sub-task did you want to parallelize but really shouldn't — too small, too coupled, or too exploratory? Write one sentence on why (§7).

Keep the result — steps 2–3 are exactly the plan you'd hand the desktop app.

Practical exercise — Run a worktree-isolated parallel merge, end to end

~35–45 minutes. Hands-on. No desktop app, no cloud account, no npm/Next.js — just Claude Code (the CLI), git, and a throwaway sandbox. You'll reproduce the chapter's core mechanics — worktree isolation, parallel edits on separate branches, and the integrate-test-then-push merge — entirely locally, so it runs anywhere. The desktop app and cloud automate these exact steps; doing them by hand once is the best way to understand what the app is doing for you.

Everything happens in a throwaway sandbox — nothing here touches the training repo.

Setup (4 min). Create a sandbox repo with a "base" feature branch, mirroring project/hookhub:

mkdir -p ~/cct-ch10-lab && cd ~/cct-ch10-lab
git init -q
printf '# HookHub (lab)\nA tiny sandbox app.\n' > README.md
printf 'h1 { color: black; }\n' > styles.css
printf 'export const features = [];\n' > features.js
git add . && git commit -q -m "init"
git branch -m main 2>/dev/null || true
git checkout -q -b project/hookhub
git commit -q --allow-empty -m "start project/hookhub"

Part 1 — one worktree, see the isolation (8 min). Create a worktree on a new branch and watch a commit land off your current branch. The portable Git mechanism (what Claude Code uses under the hood):

git worktree add ../cct-ch10-anim -b feat/animations
cd ../cct-ch10-anim
printf '\n.fade-in { animation: fade 300ms ease-in; }\n' >> styles.css
git add styles.css && git commit -q -m "feat: add fade-in animation (via worktree)"
git worktree list

Now look back at the original directory's branch:

cd ~/cct-ch10-lab
git log --oneline project/hookhub | head -3   # the animation commit is NOT here
git log --oneline feat/animations | head -3    # it lives on the worktree's branch

Expected outcome: git worktree list shows two working directories; the animation commit is on feat/animations, and project/hookhub is untouched — §3's lifecycle, proven. (Claude Code's own shortcut is claude --worktree <name>, which creates a worktree on a worktree-<name> branch and opens a session in it; we use raw git worktree here so the lab is deterministic and framework-free.)

Part 2 — a second, parallel worktree (6 min). Add a second isolated worktree for an independent feature that touches a different file (independence is the §7 rule):

git worktree add ../cct-ch10-hooks -b feat/hooks-db
cd ../cct-ch10-hooks
printf "export const features = ['repo-a','repo-b'];\n" > features.js
git add features.js && git commit -q -m "feat: seed hooks database (via worktree)"
cd ~/cct-ch10-lab && git worktree list

Expected outcome: two feature branches in two directories, each with one commit, touching different files — the parallel state of §4. (Optionally, drive the edits with Claude instead of printf: inside a worktree run claude -p "add a CSS rule named .slide-in to styles.css and commit it" to have the agent do the work — the genuinely "agentic" version.)

Part 3 — integrate on a throwaway branch, then test, then push (12 min). This is §5's pattern. Make a temporary integration branch, merge both features into it, and force a conflict to resolve:

cd ~/cct-ch10-lab
git checkout -q project/hookhub
git checkout -q -b project/hookhub-merge        # the throwaway integration branch
git merge --no-edit feat/animations             # clean merge
git merge --no-edit feat/hooks-db               # also clean (different files)

Now create a real conflict so you practice resolving one (both branches editing styles.css, like the book's CSS conflict):

git checkout -q feat/animations
printf 'h1 { color: navy; }\n' >> styles.css
git commit -q -am "style: make h1 navy"
git checkout -q feat/hooks-db
printf 'h1 { color: teal; }\n' >> styles.css
git commit -q -am "style: make h1 teal"
git checkout -q project/hookhub-merge
git merge --no-edit feat/animations             # picks up navy
git merge --no-edit feat/hooks-db               # CONFLICT in styles.css

Git reports a conflict. Resolve it (here, delegate to Claude as the chapter does, or edit by hand):

claude -p "There is a git merge conflict in styles.css in this repo. Resolve it sensibly, keeping one h1 color, then stage the file. Do not commit." 2>/dev/null || \
  printf '# resolve by hand: edit styles.css, remove the <<<< ==== >>>> markers, keep one color\n'
git diff --check                                # should report no remaining conflict markers
git commit --no-edit                            # complete the merge commit

"Test" before pushing (your stand-in for npm run dev): a trivial gate that the tree is sane:

test -f styles.css && test -f features.js && grep -q 'repo-a' features.js && echo "INTEGRATION OK"

Only after INTEGRATION OK, "push" by merging into the real target:

git checkout -q project/hookhub
git merge --no-edit project/hookhub-merge
git log --oneline | head -6

Expected outcome: the conflict appears exactly as §5 describes, you resolve it on the integration branch (never on project/hookhub directly), the "test" gate passes, and only then do both features land on project/hookhub — animations and the hooks DB coexisting. You exercised integrate → test → push with a human (you) gating the merge.

Part 4 — clean up the worktrees (4 min). §7's checklist item 4 — they don't all vanish on their own:

cd ~/cct-ch10-lab
git worktree remove ../cct-ch10-anim
git worktree remove ../cct-ch10-hooks
git worktree list                                # back to one working directory
git branch -D project/hookhub-merge              # delete the throwaway integration branch

Expected outcome: git worktree list shows a single directory again; the temporary integration branch is gone; the feature branches remain (already merged). Clean state.

Success checklist

• [ ] You created a worktree and proved a commit lands on the worktree's branch, not on project/hookhub (§3 lifecycle).
• [ ] You ran two parallel worktrees on independent files — the §4 parallel state.
• [ ] You integrated both on a temporary project/hookhub-merge branch, not directly on the target (§5).
• [ ] You hit a real merge conflict, resolved it on the integration branch, and gated the push on a passing "test" (§5 discipline).
• [ ] You cleaned up the worktrees and deleted the throwaway branch afterward (§7 checklist item 4).

Common pitfalls - Starting an agent from the wrong branch. A worktree branches from origin/HEAD by default — not necessarily the feature branch you mean. Name the starting branch explicitly and verify it (§4). A wrong base silently poisons the merge. - Merging straight into the target branch. Integrate on a throwaway branch first, resolve conflicts there, and test before you touch the real branch (§5). Never resolve conflicts on project/hookhub itself. - Assuming worktrees clean themselves up. Cleanup is conditional — named or changed worktrees prompt you, -p runs don't auto-remove. Run git worktree remove when you're done (§7). - Parallelizing coupled or tiny work. Two agents on the same file, or a two-minute task, costs more than it saves. Start sequential; parallelize only genuinely independent, well-scoped work (§7). - Expecting a "merge all branches" button. There isn't one — Claude runs standard Git in a worktree. The intelligence is in the orchestration and the human-gated approvals, not a magic command (§5). - Assuming the cloud mirrors your machine. A cloud session carries your repo-committed config (CLAUDE.md, .claude/settings.json hooks, .mcp.json, .claude skills/agents/commands) but not config that lives only on your machine (user ~/.claude/…, or servers added via claude mcp add). Commit what the session needs (§2, §6).

Knowledge check — try the quiz

Once you've read the lesson and worked the lab, take the chapter quiz from the navigation bar. Six questions: five grounded in the book chapter, one synthesis question that places this chapter's parallel-development pattern against the other "multiple agents" surfaces (subagents, agent teams, Agent View) and tests the "when to parallelize" judgment. Passing score is 5/6 — retake it until you're confident.

Further reading & enrichment sources

• Anthropic docs — "Desktop app" (https://code.claude.com/docs/en/desktop) and "Desktop quickstart" (https://code.claude.com/docs/en/desktop-quickstart). The canonical reference for the desktop Code tab and the Local / Remote / SSH environment picker — the current shape of the local-vs-cloud choice this chapter centers on.
• Anthropic docs — "Run parallel sessions with worktrees" (https://code.claude.com/docs/en/worktrees). The authoritative page on Git worktrees in Claude Code: claude --worktree, the worktree-<name> branch and .claude/worktrees/ location, the origin/HEAD base-ref default (and worktree.baseRef: "head"), and the conditional cleanup rules. Use this, not a blog, for any load-bearing worktree fact.
• Anthropic docs — "Run agents in parallel" (https://code.claude.com/docs/en/agents) and "Agent View" (https://code.claude.com/docs/en/agent-view). The wider landscape of "multiple agents" — subagents, Agent View / background sessions (claude agents), agent teams (experimental, env-gated), and dynamic workflows — so you can place this chapter's desktop parallelism among the alternatives.
• Anthropic docs — "Claude Code on the web" (https://code.claude.com/docs/en/claude-code-on-the-web) and "Remote Control" (https://code.claude.com/docs/en/remote-control). The two distinct mobile/remote paths: cloud sessions reachable from a browser/phone, versus connecting the mobile app to a session running locally on your machine.
• Anthropic blog — "Redesigning Claude Code on desktop for parallel agents" (https://claude.com/blog/claude-code-desktop-redesign). The product post behind §1 — the session sidebar, diff viewer, and parallel-session focus of the redesigned desktop app. Read it for the why of the desktop surface; verify exact feature names against the docs.
• Anthropic blog — "Agent view in Claude Code" (https://claude.com/blog/agent-view-in-claude-code) and "Claude Code on the web" (https://claude.com/blog/claude-code-on-the-web). Announcements for the background-session monitor and the cloud/web experience (isolated sandboxes, parallel cloud tasks, automatic PRs, an early iOS app) — the §2/§6 cloud story. Announcement context; treat as "as of writing, research preview."
• Anthropic engineering — "How we built our multi-agent research system" (https://www.anthropic.com/engineering/multi-agent-research-system) and "Building Effective AI Agents" (https://www.anthropic.com/research/building-effective-agents). The conceptual grounding for §4/§7 — the orchestrator-worker pattern and when parallel/multi-agent designs are worth the token cost. Treat the figures as reported background, not Claude Code behavior.
• Anthropic cookbook — "Orchestrator-workers" (https://platform.claude.com/cookbook/patterns-agents-orchestrator-workers). The runnable pattern behind "a coordinator dispatching parallel workers" — API/SDK orchestration, useful as the concept under parallel agents, not as Claude Code desktop behavior.