Have you ever wanted Claude Code to handle an API type change that spans both your frontend and backend repos in one go? Every time an API response shape changes, you end up tweaking types in the backend, updating receivers on the frontend, fixing E2E test expectations — and even as a solo developer, these manual steps quietly eat up real time.
Claude Code has a flag called --add-dir that lets you register additional working directories alongside your primary one. Once you know about it, multiple separate repositories can be treated as a single workspace for the duration of a session — no monorepo required. This article walks through the real patterns I use in my own indie app development, along with the security considerations you should understand before reaching for it.
Why --add-dir Exists in the First Place
Claude Code is designed so that, by default, it cannot touch files outside the working directory you launched it from. That guardrail exists for a good reason: it prevents the model from accidentally reading or editing something you never meant to expose.
But real development rarely fits inside a single directory. I often find myself with a frontend at frontend-app/ and a backend at api-server/ as separate repositories, both working against the same API surface. Switching between two Claude Code sessions means you lose the conversation context — the why behind the change — every time you switch sides.
--add-dir lets you register another repository as an additional target mid-session. Claude can then read and edit files across both repos within the same conversation. The real benefit isn't just access — it's that your intent, constraints, and conventions stay attached to the work, which makes cross-repo changes much more consistent.
The Basic Usage
The flag itself is refreshingly simple. You can pass it at launch, or add more directories later with a slash command.
# Add at launch (space-separated, not comma-separated)
cd ~/projects/frontend-app
claude --add-dir ~/projects/api-server
# Add during a session
# Run this inside the Claude Code prompt
/add-dir ~/projects/api-serverTo see which directories are currently attached, run /status in the prompt — it shows both your primary and any added directories. You can also chain multiple flags, which is handy when you have a microservice layout where each service lives in its own repo.
# Open three repos at once
claude \
--add-dir ~/projects/api-server \
--add-dir ~/projects/web-app \
--add-dir ~/projects/mobile-appOne constraint worth noting: you must pass a directory, not a single file. Something like ~/projects/api-server/src/types.ts will error out. This is intentional — Claude needs to see the surrounding structure to work effectively, not just a dangling file.
Pattern 1: Keeping API Types in Sync
The pattern I reach for most often is propagating a backend type change to the frontend. Let's say you're adding a timezone field to a User type in your Hono backend.
cd ~/projects/api-server
claude --add-dir ~/projects/web-appThen you give Claude the task:
Add a timezone: string field to the User type.
- api-server: update src/types/user.ts and add a DB migration.
- web-app: sync the receiving type and add a timezone selector to the profile edit screen.
- Make sure tests pass in both repos.
Claude generates the type and migration on the backend first, then updates the matching type on the frontend. Because both sides are edited in the same conversation, typos and naming mismatches almost never slip through. If you split this across two separate sessions, you'll inevitably end up with timezone on one side and timeZone on the other. --add-dir quietly eliminates that whole class of bugs.
Pattern 2: Extracting and Aligning Shared Utilities
Another recurring situation: the same logic (say, a date formatter) is duplicated across several repos, but it isn't worth publishing as an npm package. --add-dir is well-suited to this kind of lightweight cross-repo refactoring.
cd ~/projects/web-app
claude --add-dir ~/projects/mobile-app --add-dir ~/projects/admin-panelThe instruction I'd give:
Look at the three repos and find the date formatting functions used in each.
Where implementations are duplicated, pick the most complete one and align the others to match.
Make sure timezone handling is consistent across all three.
Claude greps through each repo's utils/date.ts or lib/format.ts, compares the implementations, and proposes a unified approach. What I appreciate most here is that Claude explains why it picked a particular version as the baseline — not just "this one has more lines," but actual reasoning about test coverage and error handling. That makes the review feel collaborative rather than mechanical.
Pattern 3: Docs-Driven Repo Maintenance
Documentation tends to rot when you're soloing, but --add-dir opens up a nice workflow where you start from the docs repo and use it as a lens onto the code.
cd ~/projects/docs-site
claude --add-dir ~/projects/api-serverCheck whether the API spec in docs-site/api-reference.md matches the implementation in api-server/src/routes/.
If the docs are wrong, propose corrections.
If the implementation has bugs or missing specs, surface them as issues to file.
It sounds mundane, but this is surprisingly powerful. It's essentially automated drift detection between spec and code, and it's a great fit for inventorying projects you've left alone for a few months. I run this check once a quarter against each of my personal apps.
Security and Safety Considerations
--add-dir is useful precisely because it hands Claude write access to multiple repos at once, and that's also why you should be deliberate about when you use it.
Keep Write Access to the Minimum
If a repo only needs to be read — reference code, sample implementations — the safest move is to clone it read-only at the filesystem level. Claude Code doesn't expose a per-directory write toggle, so file permissions or core.filemode are your real guardrails.
Start From a Clean Git State
Before opening a cross-repo session, run git status in each repo and make sure it's clean. Having unrelated changes pile up across multiple repos makes it genuinely confusing to decide which changes belong in which commit. I prefer to cut a fresh branch in each repo first.
cd ~/projects/api-server && git checkout -b feature/add-timezone
cd ~/projects/web-app && git checkout -b feature/add-timezone
cd ~/projects/api-server
claude --add-dir ~/projects/web-appCommit Each Repo Separately
When you ask Claude to commit "both repos," it runs git commit inside each one independently. Ask it to mention in each commit message why the change is coordinated across repos — it pays off months later when you're reading git log.
In each commit message, note that both repos are part of the same timezone field rollout.
Include any related PR numbers.
When --add-dir Isn't the Right Tool
It's not a silver bullet. A few situations where I'd reach for something else:
- Four or more repos: context consumption starts working against you, and accuracy drops. Either adopt a monorepo or break the work into parallel subagents
- Completely independent services: if the repos share no API surface and follow different conventions, mixing them just confuses Claude
- Different security boundaries: I'd avoid mixing a repo that handles customer data with one you plan to open-source. The risk of accidentally copying something sensitive is real
My rule of thumb: two to three repos, and they should all belong to the same product. Outside that range, there's usually a better tool.
How It Compares to Similar Features
A few Claude Code features overlap with this, so here's how I think about the distinctions:
--add-dir: editing multiple repos for a coordinated purpose. Shared conversation context- Worktree: working on multiple branches in a single repo. Independent working copies
- Subagent: running independent tasks in parallel. Isolated conversation contexts
The core of --add-dir isn't parallelism — it's keeping one coherent intent across multiple repos. Frame it that way and the right use cases become obvious.
A Small First Step
If you want to try this for the first time, pick an active personal project where the frontend and backend live in separate repos. Then attempt something small with --add-dir — adding a single optional parameter to one endpoint, for example. The change itself takes five minutes, but the feeling of both sides lining up perfectly on the first try is what makes it click.
To round out your cross-cutting workflows, the companion reads I recommend are Claude Code Worktree: Parallel Branch Development and Orchestrating Subagents for Parallel Work. Between those three patterns, you can cover most multi-context scenarios you'll run into.