Worktrees, Parallelism & Cost Control

Scaling Claude Code well rests on two ideas that pull in opposite directions, and the skill is holding both at once.

The first is isolation. Running several Claude sessions at once is only safe if they can't step on each other's files. A git worktree -- a separate working directory on its own branch that shares the same repository history and remote -- is the clean primitive for this. One Claude builds a feature in worktree A; another fixes a bug in worktree B; their edits never collide because they're in different directories on different branches.

The second is economy. Every one of those sessions burns tokens, and parallelism multiplies the bill. So the same lesson that teaches you to fan out also teaches you to keep each session cheap: the right model, the right effort, a hard budget ceiling, and ruthless context hygiene.

The through-line connecting them: sessions tie to directories, not branches. A session is a conversation keyed to a working-directory path; it does not snapshot your tree. Switch git branches under an open session and the files Claude sees change underneath it. Worktrees dissolve that hazard -- each branch lives in its own directory, so each gets its own session scope with no branch-switching surprises.

ONE REPO  (shared history + remote)
  ├─ main checkout        → session 1 (feature work)
  ├─ .claude/worktrees/   
  │    ├─ feature-auth/    → session 2 (isolated branch)
  │    └─ bugfix-123/      → session 3 (isolated branch)
  └─ each worktree = its own directory = its own session, no edit collisions

Pass --worktree (or -w) to create an isolated worktree and start Claude inside it. By default the worktree is created under .claude/worktrees/<value>/ at your repository root, on a new branch named worktree-<value>:

claude --worktree feature-auth

Run the same command with a different name in a second terminal and you have a second, fully isolated session:

claude --worktree bugfix-123

Omit the name and Claude generates one such as bright-running-fox. You can also just tell Claude "work in a worktree" mid-session and it creates one via the EnterWorktree tool.

Key facts to internalize:

Branch from a PR. Pass the PR number prefixed with # (or a full GitHub PR URL). Claude fetches pull/<number>/head from origin and creates the worktree at .claude/worktrees/pr-<number>:

claude --worktree "#1234"

Copy gitignored files in. A worktree is a fresh checkout, so untracked files like .env aren't present. Add a .worktreeinclude file (uses .gitignore syntax) at the project root; matching files that are also gitignored get copied into every new worktree:

.env
.env.local
config/secrets.json

Isolation is the enabler; these are the patterns that turn it into higher-quality output. There are three to keep in your toolkit.

1. Writer/Reviewer across sessions. Session A writes the code. Session B -- a fresh context with no memory of A's reasoning -- reviews it. The reviewer has no stake in the original approach, so it catches blind spots an author rationalizes away. Pair this with /code-review or /security-review in the reviewing session for structured passes. Run A and B in separate worktrees if they touch the same files.

2. Fan-out across worktrees. When a task decomposes into many independent units (migrate 20 files, fix the same lint across modules), spread them across isolated checkouts. The headless idiom from the docs:

for f in $(cat files.txt); do
  claude -p "add input validation to $f" \
    --allowedTools "Edit" "Bash(git commit *)"
done

The built-in /batch <instruction> formalizes this: it decomposes the work into 5-30 units and spawns one background subagent per unit, each in its own isolated worktree.

3. Background agents. Detach long-running work so you keep your terminal. Start with claude --bg "<task>" (prints an ID and returns) or press Ctrl+B to background the current session. Monitor everything from one screen with claude agents, tail output with claude logs <id>, and reattach with claude attach <id>.

Subagents complement all three: they run in an isolated context and report only a summary back, so heavy exploration never bloats your main thread. Set isolation: worktree in a custom subagent's frontmatter and each subagent even gets its own temporary worktree -- removed automatically when it finishes without changes.

Claude Code charges by API token consumption, so cost control starts with the two biggest dials -- which model thinks, and how hard it thinks -- then adds hard ceilings for automation.

Model choice. Sonnet handles most coding tasks well and costs less than Opus; reserve Opus for genuinely hard architecture or multi-step reasoning. Switch mid-session with /model, set a default in /config, or pass --model at launch. For cheap subagent grunt work, specify model: haiku in the subagent config.

claude --model sonnet          # default; cost-efficient for most work
claude --model opus            # reserve for hard reasoning

Effort. Extended thinking is on by default and bills as output tokens -- the default budget can be tens of thousands of tokens per request. For simple tasks, dial it down with /effort (low/medium/high/xhigh/max), set it in /model, disable thinking in /config, or cap it with MAX_THINKING_TOKENS=8000. The --effort flag sets it at launch.

Hard caps for headless/CI runs. Three flags turn an unbounded agent into a bounded job:

Combine them. A safe CI fan-out unit looks like claude -p --max-budget-usd 2 --max-turns 5 --allowedTools "Edit" "<task>" -- scoped tools, a dollar ceiling, and a turn ceiling so a runaway loop can't drain your account.

Token cost scales with context size, so the cheapest session is the one that never accumulates junk. These habits compound -- across many parallel sessions they're the difference between a $13 day and a $40 one.

• Compact at ~60%, not 95%. Run /compact [focus] manually before the window fills. Compacting early is cheaper and produces a sharper summary than waiting for auto-compaction at the limit. /compact Focus on code samples and API usage steers what survives.
• /clear between unrelated tasks. Stale context from a finished task wastes tokens on every later message. /rename first so you can /resume later, then /clear. Mixing unrelated work in one session (the "kitchen-sink" anti-pattern) is the most common silent cost leak.
• Subagents to isolate exploration. Delegate verbose operations -- reading a huge log, fetching docs, scanning a large module -- to a subagent. The verbose output stays in its context; only a summary returns to your main thread.
• MCP tool search defers definitions. MCP tool schemas are deferred by default: only tool names enter context until Claude actually uses a tool. Run /context to see what's consuming space, prefer CLI tools (gh, aws, gcloud) which add no per-tool listing, and /mcp to disable servers you aren't using.
• Trim CLAUDE.md. It loads at session start and stays even during unrelated work. Keep it under ~200 lines; move specialized workflow instructions into on-demand skills.

Track as you go. /usage (aliases /cost, /stats) shows the session's token/cost estimate plus -- on a plan -- a breakdown attributing usage to skills, subagents, plugins, and individual MCP servers (press d/w for 24h vs 7-day). /context (or /context all) shows the live breakdown of system prompt, tools, CLAUDE.md, skills, MCP, and conversation so you can see exactly where your tokens went.

Individual hygiene controls per-session cost; org-level budgets cap the total. Where you set the ceiling depends on how you authenticate.

Subscription plans (Pro / Max). Set a monthly spend limit on usage credits with /usage-credits. If you hit the limit while credits remain, Claude Code prompts you to raise or remove it without leaving the CLI (changing it needs billing access). The /usage plan view shows your bars and breakdown so you can see how close you are.

Console / API. Authenticating with a Console account auto-creates a workspace named "Claude Code" for centralized cost tracking (you can't create API keys for it -- it's auth-only). Set workspace spend limits on total Claude Code workspace spend, and a workspace rate limit on its Limits page to cap Claude Code's share so it can't starve other production workloads. Admins view cost and usage reporting in the Console; for authoritative billing, trust the Console Usage page over the locally-estimated /usage figure.

The June 15, 2026 change. Starting that date, Agent SDK and claude -p usage on subscriptions draws from a separate monthly Agent SDK credit pool, distinct from your interactive limits. Practically: your headless automation and scripted runs now consume a different bucket than your interactive coding. Budget them separately, and watch that pool independently -- a fan-out job that used to share your interactive allowance now bills against the SDK pool.