Claude Code Desktop Parallel Sessions Guide

This week the Claude Code team announced on X that the desktop app is now built for running lots of sessions side by side: sessions start faster, work is easier to split across a few of them, and you can see what each one is doing. Shortly after, @trq212 described the update as “almost like a v2”, with Desktop now able to spin off subsessions on its own.

In a one-person studio, you are the only one watching the agents, so keeping several sessions organized is most of the work. This guide covers what the official Claude Code Desktop docs say about parallel work, and a simple way to organize it so sessions don’t step on each other.

What a session is in Claude Code Desktop

In the Code tab, each conversation is a session. It has its own chat history, its own context, and its own changes, independent of every other session. The sidebar lists them all, and you can run several at once.

If you’re new to Claude Code itself, start with Part 1 of the Mastering series and come back here.

Start and arrange parallel sessions

The basics, from the docs:

The sidebar can filter sessions by status, project, or environment and group them by project. Rename sessions from the title in the toolbar. With more than two or three running, names like “paywall” or “widgets” are much easier to scan than the defaults.

Give each session its own worktree

Parallel sessions in the same folder will eventually edit the same file. For Git repositories, Desktop solves this with worktrees: select the worktree option next to the branch name when you start a session, and it gets an isolated copy of the project. Worktrees live in <project-root>/.claude/worktrees/ by default, and you can set a branch prefix in Settings > Claude Code to keep Claude-created branches easy to spot.

Two details from the worktrees guide are easy to miss. Gitignored files such as .env aren’t copied unless you list them in a .worktreeinclude file. And in a worktree session started from Desktop, project settings, hooks, skills, and .mcp.json come from the main checkout, while CLAUDE.md still loads from the worktree.

When you’re done, archive the session from the sidebar to remove its worktree, or turn on Auto-archive after PR merge or close so finished sessions clean themselves up. The architecture behind this is covered in Deep Dive 10: Worktrees & MCP.

One session per app area

Worktrees stop file collisions, but they don’t stop two sessions from making conflicting decisions about the same code. Merge conflicts still happen at the end if two branches rewrite the same view.

One way to set this up is to split sessions by area of the app rather than by task size. For an app like Molip, that could mean one session on the timer and Screen Time blocking, one on insights and charts, and one on App Store metadata or the website. Each area has its own files, so the sessions rarely touch the same thing, and each session’s context stays about one part of the app.

A few rules make this work:

1. Name every session after its area.
2. Start each one in its own worktree.
3. Keep shared code (models, design tokens) in a single session, or change it yourself between sessions.
4. Merge one branch at a time, so each PR is reviewed on its own.

Running more sessions also multiplies token usage. The parallel agents docs say this directly, so a few well-scoped sessions beat many vague ones.

Subsessions, subagents, and forks

“Subsessions” is the word used in the announcement. The docs describe several related tools, and they behave differently:

• Subagents work inside one session. They take a side task in their own context and return a summary, which keeps search results and logs out of your main conversation. Custom subagents can set isolation: worktree to always get their own worktree. See Part 3: Skills & Subagents for setup.
• /subtask starts a forked subagent that inherits the whole conversation so far, so you don’t have to re-explain the situation.
• /fork copies the session into a new background session that runs alongside it.
• Side chats (Cmd+; or /btw) let you ask a question using the session’s context without adding anything back to the main thread. They aren’t saved after you close the app.

A practical split: use a side chat for “what does this function do?”, a subagent for “search the codebase and report back”, and a separate worktree session for work that edits files in a different area.

Let sessions talk to each other

Desktop can work across sessions. Ask in plain language, for example “what did the widgets session conclude?” or “tell the insights session the data model changed”, and Claude reads the other session’s history or sends it a message. Messages show up as a card labeled with the sender’s title. If the receiving session is mid-task, the message waits until its current work finishes.

This surface sees only sessions the desktop app runs itself (local, SSH, WSL), by default the 20 most recently active. It doesn’t see cloud sessions or ones started from the terminal CLI or VS Code. For those, the docs point to cross-session messaging.

How to spot a stuck session

With several sessions running, the risk is that one quietly stops making progress while you watch another. Desktop gives you a few signals:

• Notifications. The app sends an OS notification when a session finishes a task and you aren’t viewing it. If one you expected to finish stays silent, look at it.
• Status filters. Filter the sidebar by status to see where each session stands at a glance.
• The tasks pane. Open Background tasks from the title bar’s ⋮ menu, or run /tasks, to see subagents, background shell commands, and workflows in the current session. Click an entry to read its output or stop it. A shell command that has printed nothing new for a long time is a good place to start.
• Ask another session. Claude can read what another session has been doing and summarize it for you.
• Context usage. When context fills, Claude summarizes the conversation and keeps going. You can trigger this earlier with /compact. A session that keeps repeating itself after many compactions is usually better restarted with a clear, smaller task.

For long jobs, the docs also suggest a Notification hook with the permission_prompt matcher, so you hear about a waiting approval instead of discovering it later. Hooks are covered in Part 5, and how background work is modeled is in Deep Dive 8: Tasks & Background Jobs.

Where agent teams fit

Agent teams, where a lead assigns work to teammates from a shared task list, are available in the CLI, not in Desktop, and are experimental and off by default. In Desktop, the docs recommend dynamic workflows for multi-agent work inside one session, plus cross-session messaging. If you want the theory, Deep Dive 9 walks through how team coordination works.

Sources

• Claude Code Desktop docs: code.claude.com/docs/en/desktop
• Run agents in parallel: code.claude.com/docs/en/agents
• Worktrees: code.claude.com/docs/en/worktrees
• Subagents: code.claude.com/docs/en/sub-agents
• Announcement: @ClaudeDevs on X
• Desktop v2 and subsessions: @trq212 on X