Blog Working with agents
Running One Coding Agent Across Six Client Repos Without Context Bleed
A working setup for freelancers and small studios running one AI agent over many client codebases without instructions crossing between them.
The short answer
Context bleed between client codebases has three mechanical causes: a global configuration file carrying rules meant for one project, a single agent session left open across two repositories at once, and notes that never record which project they apply to. Claude Code, Codex CLI, and Gemini CLI all resolve their instruction files (CLAUDE.md, AGENTS.md, and GEMINI.md) the same way, by walking up from the current working directory to a project root and loading whatever they find along that path. The fix that removes most of the problem is one git working directory per client project, with per-project instructions and memory kept inside that folder instead of in machine-wide configuration.
You have six client folders on this machine and one terminal habit: open whichever one needs attention, run the agent, move on. Then one afternoon the agent tells a fintech client's codebase to use the tab width and commit style of the WordPress site you fixed that morning. This post names the three mechanical reasons that happens, gives the rule that prevents most of it, and covers the monorepo exception honestly rather than pretending it doesn't complicate things.
What context bleed actually looks like when it happens to you
It rarely announces itself. The agent doesn't flag "now applying Project A's rules to Project B." It just quietly does the wrong thing with total confidence, and the pattern repeats in a handful of recognizable shapes:
- It names a function or a file the way the last repo you worked in wanted, not this one.
- It reaches for a testing library or a package manager this client's project doesn't use.
- It references a decision, a deploy step, or a workaround that belongs to a different codebase entirely.
- It applies a formatting rule from your global config to a project that has its own, conflicting one.
You notice on review, not in the moment, which is what makes it expensive. Multiply that by six active client repos and the failure mode stops being occasional and starts being structural. It isn't a model problem. It's a scope problem: something that should have applied to one project got read into another.
Cause 1: global config doing a per-project job
The most common source is a single file at the top of the tree doing work that should have stayed local. Claude Code reads a CLAUDE.md at ~/.claude/CLAUDE.md on every session, across every project, by design, described as the place for "personal preferences for all projects" in Anthropic's own documentation. That's correct for your own formatting taste or a shortcut you always want available. It's wrong the moment someone pastes a client-specific build command or naming convention in there because it was convenient at the time. A related version of the same mistake, a CLAUDE.md so long the agent stops reading half of it, is covered in why a bloated CLAUDE.md gets ignored. Ask whether a rule is true of every project you touch, or just this one.
Cause 2: one agent session, two repositories
The second cause is simpler and more common than people expect: literally having both repositories in scope of one running session. Claude Code's own MCP server documentation describes three configuration scopes, local, project, and user, and the same layering exists for --add-dir, which grants a session access to a second directory without switching out of the first. That's legitimate for a genuinely shared task. It's a liability when it's just how you avoid opening a second terminal tab, because every tool call the agent makes can now touch either repository, and nothing forces it to keep the two apart.
Cause 3: notes that never say which project they belong to
The third cause is the quietest: a scratch file, a personal wiki page, or a running Slack thread of "things the agent should remember," none of which record which client it was about. Read back three weeks later, a note like "switched to the async version because the sync one times out" is useless without the project name attached, and the same failure shows up in the plainest version of this workflow, described in why a todo.md file stops working past the third session. A gotcha with no project name isn't a gotcha. It's a coin flip the next session has to make blind.
One folder, one project: the rule that removes most of it
Almost everything above collapses under one rule: one git working directory per client project, and nothing that describes that client's codebase lives anywhere else. Claude Code, Codex CLI, and Gemini CLI all agree on the mechanism even though they disagree on the filename. Claude Code loads CLAUDE.md and CLAUDE.local.md from your working directory and every directory above it, concatenated from the filesystem root down to where you launched it. Codex CLI walks up from the working directory to a project root, by default wherever it finds a .git folder, loading AGENTS.md and .codex/config.toml at each level. Gemini CLI does the same for GEMINI.md, described in Google's own documentation as a hierarchy of a global file in your home directory plus whatever it finds walking from your workspace root down to the current directory. In all three, the working directory is the unit of scope. Keep one client per folder and the tool does the separating for you.
This is also the exact mechanic Trail builds its connector around. The npm package, listed in the official MCP registry as dev.usetrail/trail, describes itself as giving an agent "your team's tracker and the project's durable memory, scoped to the folder you have open." Switching projects means switching folders, not remembering to pass a project ID, across Claude Code, Codex, and Gemini CLI alike, so the six-repo habit you already have is the whole setup, not a workaround.
The monorepo exception, and directory-scoped configuration
The honest exception is a monorepo, where two clients or two products genuinely share one git root. Here the one-folder rule needs a second layer: directory-scoped instructions instead of directory-scoped repositories, and all three tools support it. Claude Code discovers nested CLAUDE.md files in subdirectories on demand as it reads files there, and its .claude/rules/ directory can scope a rule to a glob like packages/billing/** so it never applies to packages/marketing/. Codex CLI layers .codex/config.toml and AGENTS.md the same way, walking from the project root down to your working directory and letting the file closest to where you're working win. The cross-vendor AGENTS.md spec formalizes this as standard behavior: an agent should use the closest file in the directory hierarchy, so a nested file overrides the root one rather than fighting it.
If the two halves genuinely need to diverge for a stretch of work, git worktree is the closer tool: it checks out a second working directory from the same repository on its own branch, so an agent session in one worktree isn't reading files that belong to work happening in the other.
What has to be per-project and what can safely stay global
Not everything belongs in the client folder, and treating it that way just means retyping the same three lines six times. The test is whether a rule is true regardless of which codebase you're in. The same split applies to settings.json: Claude Code's own configuration layers from managed policy down through project and user scopes, so permissions and hooks that are genuinely project-specific belong in a project's .claude/settings.json, not ~/.claude/settings.json.
| Belongs in the project folder | Safe to keep global |
|---|---|
| Build and test commands | Your own editor and formatting preferences |
| Architecture notes and gotchas | Shell aliases and personal shortcuts |
| Client-specific naming conventions | A default model or CLI flag you always want |
| That project's decisions and their reasoning | General coding style you apply everywhere |
This isn't a new problem that AI agents invented. direnv has solved the equivalent problem for environment variables for over a decade, loading and unloading them automatically as you cd into and out of a directory with an .envrc file. The instinct is the same one this whole rule is built on: attach the setting to the folder, not to the machine.
Keeping six projects without keeping six terminals open
The one-folder rule doesn't mean six terminal tabs held open at once. It means whichever project you're in gets that project's rules and nothing else's, a property of the folder, not of how many windows are visible on screen. A terminal multiplexer, or simply closing and reopening a working directory between clients, gets you the isolation without the overhead. What you're avoiding isn't "having many projects." It's having one blurred one.
The four-minute Monday routine
A short routine at the start of the week, about four minutes, catches drift before it compounds:
- Open each client's project folder in turn and skim its root instruction file. Does anything in it read like it belongs to a different client?
- Check for stray notes outside the project folder, in a personal scratchpad or a chat thread, that describe one specific codebase.
- Confirm no
--add-diror equivalent flag is still pointed at a second repository from last week's session. - If a monorepo directory has grown a rule that should now be its own subdirectory-scoped file, split it before it drifts further.
Four minutes, once a week, against a habit that costs far more than that to unwind after the fact.
When a client asks what happened on their project last week
This is the moment the whole setup gets tested. If everything about a project, its instructions and its memory, lived inside that project's folder, the answer is sitting right there. If it didn't, you're reconstructing from commit messages and memory, and commit messages rarely say what got skipped or why, only what got merged.
A freelancer running one or two active clients can get by on discipline alone: one folder, one root instruction file, a plain changelog kept inside the repo. A small studio running five or six needs something closer to structural enforcement, because discipline that has to hold across three people and six repos stops being free. That's the harder version of the same problem, and it's the one an agent-native issue tracker is built to answer: a record scoped to the project, not to whoever remembers to write it down. If the instruction-file side of this problem is the piece you still need sorted out, the differences between CLAUDE.md, AGENTS.md, and GEMINI.md are laid out directly in CLAUDE.md vs AGENTS.md vs GEMINI.md.
What to remember
- Context bleed has three mechanical causes: global config carrying project-specific rules, one agent session open across two repositories, and notes that never name the project they belong to.
- Claude Code loads CLAUDE.md files from the working directory and every directory above it, concatenating them from the filesystem root down to the working directory.
- Codex CLI and Gemini CLI both resolve their own instruction files the same way, walking up from the working directory to a project root and loading directory-scoped files along the way.
- The fix is one git working directory per client, one agent session per working directory, and no notes file that lacks a project name on its first line.
- Git worktrees and monorepo path-scoped rules are the two legitimate exceptions to the one-folder-one-project rule.
- Trail's MCP connector scopes itself to the folder the agent is running in, so switching projects means switching folders, not passing a project ID.
Questions people ask
Why does my AI coding agent mix up context between two different projects?
Usually one of three things is happening. A global CLAUDE.md, AGENTS.md, or GEMINI.md file in your home directory carries rules that only apply to one client's codebase, the same terminal session has two repositories open at once, or a plain notes file was written without saying which project it belongs to. Claude Code, Codex CLI, and Gemini CLI all load instruction files by walking up from your current working directory, so a rule that lives too high up that path reaches every project you open, not just the one it was written for.
Can one Claude Code session cover two repositories at once?
Claude Code allows this with flags like --add-dir to give a session access to a second directory, but CLAUDE.md files from that added directory are not loaded by default. Running two separate agent sessions, each scoped to its own repository in its own terminal tab, is the more reliable pattern and avoids the agent quietly carrying conventions from whichever repo it read from most recently.
Does a monorepo break the one-folder-one-project rule?
Not if you use directory-scoped instructions. Claude Code, Codex CLI, and Gemini CLI all support nested instruction files inside subdirectories that layer on top of or override the root file, so a billing package inside a monorepo can carry its own rules without leaking into a marketing package next to it. Claude Code's path-scoped rules work the same way for individual files.
What should stay in global config versus per-project config?
Keep genuinely tool-wide preferences, like your own formatting taste or shell aliases, in global config, since those hold regardless of which client's code you're touching. Anything that describes one codebase specifically, its build commands, its architecture, its house style, its gotchas, belongs inside that project's own folder, not in a file every project reads by default.
How do you track what an AI agent did on a specific client project last week?
Keep a record scoped to the project rather than to your own memory or a shared inbox, such as a per-project changelog or an issue tracker the agent writes to as it works. Commit messages alone rarely answer what a client actually asks, which is what got skipped or changed and why, not just what got merged.
