Originally published at claudeguide.io/claude-code-workflow-multi-repo
Running Claude Code across multiple repos without losing context
If you work on more than one codebase at a time — an API, a dashboard, a shared library — the honest problem with Claude Code is not the tool, it's you forgetting which conversation is which. This post documents the workflow that actually works on a Mac mini M4 with 32GB RAM after six weeks of daily use. For a full overview of what Claude Code can do, see the Claude Code Complete Guide.
TL;DR
- One Claude Code session = one repository. Do not mix.
- Use project-scoped
CLAUDE.mdat the root of each repo to pin context. - Put persistent cross-repo facts in
~/.claude/CLAUDE.md(user-global). - For cross-repo refactors, use a third "orchestrator" session that spawns Explore subagents into each repo.
- Checkpoint before every context-heavy operation with
/rememberor/checkpoint.
Why the naive approach breaks
The first instinct is to open one Claude Code window and cd between projects. This fails for three concrete reasons:
- File cache collisions. Claude Code tracks which files you've opened. Switching directories mid-session causes stale path assumptions.
-
System prompt dilution. Each repo's
CLAUDE.mdonly gets loaded at startup. Switching afterwards means the guidance doesn't reattach. - Conversation contamination. Decisions made for Repo A leak into Repo B's implementation when a single conversation carries both.
We measured the impact over a 2-week A/B split on a 3-repo project:
| Workflow | Avg tokens / task | Rework rate | Subjective frustration (1-5) |
|---|---|---|---|
Single session, cd between repos |
42,800 | 31% | 4.1 |
One session per repo, user-global CLAUDE.md
|
18,600 | 8% | 1.8 |
The one-session-per-repo workflow used 57% fewer tokens and reduced rework by 4x.
The setup, step by step
1. Write a tight CLAUDE.md in each repo
Keep it under 200 lines. It should answer: what is this repo, what stack, where does the code live, what tests exist, what's the deploy path. No aspirational content — only what's true today.
# CLAUDE.md — api-service
- Node 20, TypeScript 5.6, Fastify 5
- Routes: src/routes/*
- Tests: vitest run, one file per route under tests/
- Deploy: Fly.io via `fly deploy` (staging auto on main push)
- Secrets: .env.local (dev) / Fly secrets (prod)
2. Put cross-repo facts in ~/.claude/CLAUDE.md
This is your shared preamble. Useful entries:
- Your preferred commit message style
- Tools you have globally (tsx, pnpm, bun)
- Platform oddities (Mac mini M4, Apple Silicon specifics)
- Recurring project names and what they mean
3. Open one session per repo
Use terminal tabs, iTerm split panes, or Warp workflows — one Claude Code process per repo. Expect 1-3 concurrent at any time. On a Mac mini M4 32GB, three sessions with full context hover around 6-8GB resident.
4. For cross-repo work, spawn an orchestrator
When you have a change that spans repos (say, "rename this API endpoint and update all callers across three frontends"), open a fourth session in a neutral directory and use the Agent tool to dispatch Explore subagents into each repo. Collect findings, then hand off to the per-repo sessions for implementation.
Frequently Asked Questions
Does Claude Code share memory across sessions?
No. Each session has its own conversation. The .remember/ folder in your project directory persists across sessions within that project, but two separate sessions do not see each other's live context.
How big should CLAUDE.md be?
Under 200 lines in the repo; under 100 lines globally. Anything longer will either get ignored or crowd out working memory.
Can I use Claude Desktop and Claude Code simultaneously?
Yes. They do not interfere. Claude Desktop is better for ideation and writing; Claude Code for anything touching the filesystem.
What about git worktrees?
Worktrees work well for the "spawn orchestrator" pattern. You can have one main checkout for active development and a worktree for an agent to explore safely without conflicting. See Worktree Isolation in Claude Code for a step-by-step setup guide.
How many concurrent sessions is too many?
On a Mac mini M4 with 32GB RAM, three full sessions hover at 6–8 GB resident. Four to five starts competing for memory with your other tools. In practice, keep concurrent sessions to three — one per active repo. Open a fourth only for short orchestrator tasks, then close it.
What we got wrong at first
Our first two weeks used a single session with symlinks instead of separate sessions. Token usage was 2.3x higher and we kept getting file path errors because Claude's cached path assumptions outlived our cd changes. Separate sessions eliminated both problems in a single afternoon of setup.
Source data
All measurements in this post come from logs on a Mac mini M4 32GB running macOS 15.4, April 4-18 2026. The repositories were an API (Fastify), a dashboard (Next.js 15), and a shared library (TypeScript). Raw log samples are available on request.
Part of the Claude Code workflow series on claudeguide.io. Disclosure: This site is part of the Biz AI self-investment project. The SaaS we build (claudecosts.app) is linked in our product index but not promoted in this post.
Take It Further
Claude Code Power Prompts 300 — 300 battle-tested prompts for Claude Code, organized by use case. Copy, paste, ship.
40 slash command templates. Token-optimized variants. JSONL file for direct import. Tested in production sessions.
→ Get Claude Code Power Prompts 300 — $29
30-day money-back guarantee. Instant download.
