{"slug": "running-claude-code-across-multiple-repos-without-losing-context", "title": "Running Claude Code across multiple repos without losing context", "summary": "The article recommends using one dedicated Claude Code session per repository when working across multiple codebases, as switching between projects within a single session leads to 57% more token usage and 4x more rework. It advises creating a concise `CLAUDE.md` file (under 200 lines) in each repo to define the stack, tests, and deploy path, while using a global `~/.claude/CLAUDE.md` for shared preferences. For cross-repo changes, the author suggests opening a fourth session in a neutral directory to dispatch exploration agents, then implementing changes in the dedicated per-repo sessions.", "body_md": "Originally published at claudeguide.io/claude-code-workflow-multi-repo\nIf 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.\nCLAUDE.md\nat the root of each repo to pin context.~/.claude/CLAUDE.md\n(user-global)./remember\nor /checkpoint\n.The first instinct is to open one Claude Code window and cd\nbetween projects. This fails for three concrete reasons:\nCLAUDE.md\nonly gets loaded at startup. Switching afterwards means the guidance doesn't reattach.We measured the impact over a 2-week A/B split on a 3-repo project:\nThe one-session-per-repo workflow used 57% fewer tokens and reduced rework by 4x.\nCLAUDE.md\nin each repo\nKeep 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.\n# CLAUDE.md — api-service\n- Node 20, TypeScript 5.6, Fastify 5\n- Routes: src/routes/*\n- Tests: vitest run, one file per route under tests/\n- Deploy: Fly.io via `fly deploy` (staging auto on main push)\n- Secrets: .env.local (dev) / Fly secrets (prod)\n~/.claude/CLAUDE.md\nThis is your shared preamble. Useful entries:\nUse 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.\nWhen 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.\nNo. Each session has its own conversation. The .remember/\nfolder in your project directory persists across sessions within that project, but two separate sessions do not see each other's live context.\nUnder 200 lines in the repo; under 100 lines globally. Anything longer will either get ignored or crowd out working memory.\nYes. They do not interfere. Claude Desktop is better for ideation and writing; Claude Code for anything touching the filesystem.\nWorktrees 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.\nOn 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.\nOur 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\nchanges. Separate sessions eliminated both problems in a single afternoon of setup.\nAll 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.\nPart 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.\nClaude Code Power Prompts 300 — 300 battle-tested prompts for Claude Code, organized by use case. Copy, paste, ship.\n40 slash command templates. Token-optimized variants. JSONL file for direct import. Tested in production sessions.\n→ Get Claude Code Power Prompts 300 — $29\n30-day money-back guarantee. Instant download.", "url": "https://wpnews.pro/news/running-claude-code-across-multiple-repos-without-losing-context", "canonical_source": "https://dev.to/claudeguide/running-claude-code-across-multiple-repos-without-losing-context-2k83", "published_at": "2026-05-23 01:30:02+00:00", "updated_at": "2026-05-23 02:31:59.040604+00:00", "lang": "en", "topics": ["developer-tools", "artificial-intelligence", "large-language-models"], "entities": ["Claude Code", "Claude", "Mac mini M4", "Fly.io", "Fastify", "Node", "TypeScript", "iTerm"], "alternates": {"html": "https://wpnews.pro/news/running-claude-code-across-multiple-repos-without-losing-context", "markdown": "https://wpnews.pro/news/running-claude-code-across-multiple-repos-without-losing-context.md", "text": "https://wpnews.pro/news/running-claude-code-across-multiple-repos-without-losing-context.txt", "jsonld": "https://wpnews.pro/news/running-claude-code-across-multiple-repos-without-losing-context.jsonld"}}