# How to manage multiple Claude Code sessions on a Mac (2026)

> Six ways to run several Claude Code sessions at once — terminal tabs, --worktree, the built-in claude agents view, the desktop app, tmux tools, and CmdBrief — with the commands, a comparison table, and the failure each one is prone to.

- **Category:** Workflows
- **Updated:** 2026-09-29
- **Reading time:** 7 min
- **Canonical page:** https://cmdbrief.com/guides/manage-multiple-claude-code-sessions

## The short answer

Claude Code already ships three ways to run sessions in parallel: open a second terminal and run `claude --worktree <name>` so each session gets its own checkout, run `claude agents` for a single-screen dashboard of background sessions, or use the desktop app, where each new session can take its own worktree. All three are included with a Pro or Max plan.

Pick by two questions. Do the sessions share a repository? If yes, you need worktree isolation, which the first and third options give you for free. Are you supervising one product or several, and one vendor or several? If it is several of either, the built-in tools stop short — they show you Claude sessions, not your portfolio — and that is where tmux-based tools or [CmdBrief](https://cmdbrief.com/) come in.

> **Tip:** Original command checks used Claude Code 2.1.237 on macOS on 2026-08-20. The worktree guidance and --worktree / --resume flags were rechecked on 2026-09-07 against current documentation and installed CLI help. Use `claude --help` for your installed version.

## Why parallel sessions go wrong

Two Claude Code sessions in the same directory will happily edit the same files. Nothing stops session A from reformatting a file session B is midway through changing; the symptom is a diff that neither session can explain. A second, quieter failure is attention: with four terminals open you will miss the one that has been waiting twenty minutes for a permission prompt. A third is capacity: every session draws from the same 5-hour and weekly usage windows, so parallelism spends your limit faster, not slower.

The options below solve the first problem (isolation) to varying degrees, the second (visibility) in very different ways, and none of them solve the third — which is why usage windows deserve their own screen real estate.

## The options, compared

| Option | Isolation | Status visibility | Usage windows | Resume | Cost | Best for |
| --- | --- | --- | --- | --- | --- | --- |
| Terminal tabs, one `claude` each | None — same checkout | Tab titles only | In-session `/usage` | `claude --continue` per directory | Free | Two sessions in two different repos |
| `claude --worktree` per terminal | Full — one worktree per session | Tab titles only | In-session `/usage` | Re-enters its worktree | Free | Several tasks in one repo |
| `claude agents` (built-in view) | Same as whatever you launched with | Needs input / Working / Completed list | Not shown in the list | Attach with Enter | Free | Many Claude sessions, one screen |
| Claude Code desktop app | Optional — a worktree per session when you choose it | Sessions sidebar, grouped by project | Usage ring (plan level) | Sidebar history | Included with Pro/Max | One vendor, GUI preferred |
| tmux + Claude Squad / CCManager | Worktree per session (tools create them) | Pane list with busy / waiting states | No | Pause / resume in tool | Free, open source | Terminal purists, multiple CLIs |
| CmdBrief | Your checkouts; worktrees only for a lead’s code builders | Attention rolled up across products and six supported agent CLIs | Side by side per vendor (5h, 7d, credits) | Cross-provider session list | €29.99/mo, 14-day refund | Several products, several vendors, one Mac window |

*Verified against the Claude Code docs and each tool’s README on 2026-08-20; the desktop row re-checked on 2026-09-29. Claude Code desktop and agents view details: code.claude.com/docs.*

## Option 1: one worktree per session with --worktree

This is the smallest change from "just open another tab" that actually fixes the collision problem. Claude Code creates a git worktree under `.claude/worktrees/<name>/` on a new branch called `worktree-<name>`, starts the session inside it, and keeps its normal file edits separate. A worktree is not a security sandbox: tool permissions and shared services still need their own boundaries.

**two isolated sessions in one repository**

```bash
cd ~/src/app
claude --worktree auth-refresh      # terminal 1
claude --worktree billing-webhooks  # terminal 2

git worktree list                   # see both checkouts

```

1. Commit at least once first — worktrees branch from an existing commit, and an empty repo fails with `Failed to resolve base branch "HEAD"`.
2. Add `.claude/worktrees/` to `.gitignore` so the worktrees do not show up as untracked files in the main checkout.
3. Initialize each checkout from the project’s development example files. If you use `.worktreeinclude`, list only the local files each new checkout actually needs; do not copy production credentials automatically.
4. Install dependencies inside the worktree — it is a fresh checkout, and `node_modules` does not come along.
5. On exit, Claude asks whether to keep or remove a worktree that has work in it; a clean, unnamed one is removed automatically.

**.worktreeinclude**

```text
.env.development.local
# Only include a development file you have reviewed.

```

> **Warning:** Worktrees branch from the remote default branch by default, not from your current branch. If you are isolating work that depends on unpushed commits, set `"worktree": { "baseRef": "head" }` in `~/.claude/settings.json` or you will be debugging a worktree that is missing your last three commits.

## Option 2: the built-in agents view

If the problem is not isolation but attention, `claude agents` is the tool Anthropic built for it. It takes over the terminal with a list of background sessions grouped into Needs input, Working, and Completed, each row showing the session name, what it is doing, and its age. You dispatch a new session by typing a prompt, peek at one with Space, attach with Enter, and background the current one with the left arrow on an empty prompt.

**one screen for many sessions**

```bash
claude agents

```

Two limits to know. Sessions run locally and do not survive a shutdown, and each one still consumes your usage windows independently — the view does not show those windows, so check `/usage` inside a session before dispatching a fifth task on a Friday afternoon.

## Option 3: the desktop app

The Claude Code desktop app does both of the above in a GUI: a new session (Cmd+N) gets its own worktree when you pick the worktree option next to the branch name, the sidebar groups sessions by project and filters by state, you can open two sessions side by side, and there is a diff view, a terminal pane, and a browser pane. It is included with Pro and Max. For a developer working on one product with one vendor it is hard to argue for anything else.

What it does not do is look past Claude. A Codex thread, a Grok CLI run, or an OpenCode session in the same product is invisible to it, and its usage indicator covers your Anthropic plan only.

## Option 4: tmux with Claude Squad or CCManager

The terminal-native answer. [Claude Squad](https://github.com/smtg-ai/claude-squad) creates a tmux session and a worktree per agent, shows a list with diff and pause/resume, and supports Claude Code, Codex, Gemini, Aider, OpenCode, and Amp. [CCManager](https://github.com/kbwo/ccmanager) is a TUI session manager for nine CLIs with busy/waiting/idle states. Both are free and open source.

**Claude Squad via Homebrew**

```bash
brew install claude-squad
cs                      # opens the session list; n = new session

```

The people who wrote the popular tmux + worktree guides are candid about the ceiling: no view of which branch a worktree was last rebased on, a mental map of dev-server ports, and coordination overhead that eats the gains somewhere around three to five agents. These tools push that ceiling out; they do not remove it.

## Option 5: several products, several vendors — CmdBrief

Everything above is organised around sessions inside a project. If your day is five products at five stages, with Claude Code on two of them and Codex on a third, the unit you supervise is the product, not the session. CmdBrief gives each product a persistent workspace — agents, tasks, terminals, diff viewer, browser panes — and rolls attention up across all of them: which product has an agent that needs you, which is working, which finished. It supervises Claude Code, Codex, Grok CLI, Kimi CLI, OpenCode, and Cursor CLI with the same status states, and shows each vendor’s usage windows side by side: Claude 5-hour and weekly, Codex weekly, Grok weekly credits, OpenCode rolling and monthly, Cursor CLI monthly Cursor-models and Other-models pools.

It is a paid, local-first, macOS-only Rust app (€29.99 a month, 14-day money-back), and it creates worktrees only for the code builders a lead agent starts — for sessions you open yourself, bring your own checkouts or pair it with `claude --worktree` from option 1. See the [features](https://cmdbrief.com/features) page for the full list.

## Resuming sessions, whichever option you chose

Claude Code saves every conversation locally, so parallel work survives closing the terminal. The two flags you need:

**resume**

```bash
claude --continue            # most recent session in this directory
claude --resume              # pick from a list (or /resume inside a session)
claude --resume --fork-session   # branch a new session off an old one

```

A session started with `--worktree` returns to its worktree on resume. Launch the resume from the main checkout, not from inside the worktree — launching from inside is the most common reason a resume lands outside its worktree.

## A failure to expect: two sessions, one checkout, one formatter

The classic. Session A is told to "fix the failing tests in payments"; session B is told to "tidy up the imports across src". Both are in the same directory. B runs the formatter on twenty files, including the one A has half-edited. A’s next edit fails with an old-string mismatch, it re-reads the file, and re-applies its change on top of B’s reformat — or worse, reverts it. You find out at review time when the diff touches 24 files for a one-function fix.

The fix is any isolation option above. The cheaper discipline, if you insist on one checkout, is to give each session a disjoint write scope in its first prompt and never hand two sessions the same directory.

## Questions

### Can I run multiple Claude Code sessions at the same time?

Yes. Open separate terminals, or use `claude --worktree <name>` to give each session its own checkout, or `claude agents` for a single-screen view of background sessions. In the desktop app, each new session can take its own worktree.

### Do parallel sessions share my usage limit?

Yes. Sessions share the account’s provider allowance. Consumption depends on model, context, tool use, and idle time, so four sessions do not imply an exact fourfold rate. Check /usage before dispatching more work.

### Is there a built-in Claude Code session manager?

Two: `claude agents` in the CLI, which lists background sessions by Needs input / Working / Completed, and the desktop app’s sessions sidebar. Third-party managers add multi-vendor support, tmux integration, or portfolio-level supervision.

### When do I need something beyond the built-in tools?

When you supervise more than one product, more than one agent vendor, or want usage windows from several vendors on one screen. The built-in tools are per-vendor and organised by project.

## Primary sources

Provider terms and product behavior can change. Confirm plan, pricing, model, and permission details in the current official documentation.

- [Claude Code docs: run parallel sessions with worktrees](https://code.claude.com/docs/en/worktrees)
- [Claude Code docs: agent view](https://code.claude.com/docs/en/agent-view)
- [Claude Code docs: desktop app](https://code.claude.com/docs/en/desktop)
- [Claude Code docs: common workflows (resume)](https://code.claude.com/docs/en/common-workflows)
- [Claude Squad README](https://github.com/smtg-ai/claude-squad)
- [CCManager README](https://github.com/kbwo/ccmanager)

## Keep reading

- Comparisons: [Claude Code GUI for Mac: the options compared (2026)](https://cmdbrief.com/guides/claude-code-gui-mac)
- Workflows: [Run Claude Code and Codex in parallel with Git worktrees](https://cmdbrief.com/guides/run-claude-code-and-codex-in-parallel)
- Usage and plans: [Claude Code usage limits: check usage, resets, and interruptions](https://cmdbrief.com/guides/claude-code-usage-limits)

---

Markdown mirror of https://cmdbrief.com/guides/manage-multiple-claude-code-sessions, generated at build time from the same data the HTML page renders. Machine-readable index: https://cmdbrief.com/llms.txt