# Use Claude Code with multiple repositories
> Claude Code reaches other repos with --add-dir; ivar adds one feature branch, one plan and one pull request per repo across them.
Source: https://ivar.run/docs/with/claude-code

Claude Code can read and edit directories beyond the one it starts in, using `--add-dir`. `ivar` adds the part that comes after file access: one feature branch across the repos, a write scope that is guarded (kernel-enforced on Linux; see [Limitations](/docs/reference/limitations)) on the repos you have not promoted, one plan, and one pull request per repo.

## What Claude Code does on its own

As of 2026-10-06, Claude Code's own options for several directories are these:

- **`--add-dir`, `/add-dir` and `additionalDirectories`** extend the directories Claude Code works in. Files there follow the same permission rules as the original directory ([Claude Code permissions](https://code.claude.com/docs/en/permissions#working-directories), accessed 2026-10-06).
- **Access, not configuration.** Most of `.claude/` in an added directory is not loaded. `.claude/skills/`, `.claude/commands/`, `.claude/agents/` and the `enabledPlugins` and `extraKnownMarketplaces` keys are. `CLAUDE.md` loads from an added directory only with `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1` (same page, accessed 2026-10-06).
- **Projects** (beta, Pro and Max plans) clone every repository of a project into each thread, which works on its own branch and opens a PR. They need github.com and the Claude GitHub App. With several repositories, permission rules, hooks and `env` don't apply ([Claude Projects](https://code.claude.com/docs/en/claude-projects), accessed 2026-10-06).

Whether `--add-dir` creates a shared branch across local directories is not documented.

## Install and create a hall

```sh
curl -fsSL https://ivar.run/install | sh
ivar init --provider claude-code
```

In an existing hall, `ivar provider add claude-code` registers the provider. Add each repo with `ivar repo add <name> <url>`. The [quickstart](/docs/quickstart) walks through it.

## One change across repos

The example hall has `api`, `web`, `shared-types` and `infra`. The request: add an `avatarUrl` field to the user profile, return it from the API and render it on the web profile page.

```sh
ivar feature create avatar-url
ivar feature promote avatar-url api
ivar feature promote avatar-url web
ivar feature promote avatar-url shared-types
ivar session start avatar-url
```

Inside the session, run `/ivar-plan` and approve each gate. Then, from the hall:

```sh
ivar feature deliver avatar-url --preview
```

The preview lists three pull requests: `api`, `web` and `shared-types`. `infra` stays guarded and gets none.

## What lands in the session

A Claude Code session gets `CLAUDE.md`, the hall's skills and the `/ivar-*` commands in `.claude/`, plus a pre-tool hook for the write guard. Every repo you promoted sits in the view dir on the feature's branch. See [the Claude Code provider](/docs/providers/claude-code).

## MCP servers

Declare each server once in `ivar.json`. `ivar sync` writes it to `.mcp.json`, and `ivar mcp auth` handles OAuth. See [MCP for Claude Code](/docs/guide/mcp/providers/claude-code).

## Limits

- `ivar` runs on Linux and macOS. Windows is not supported.
- Claude Code's `--add-dir` needs no hall, so a hall costs setup time you only recover once the change spans more than one repo.
- The Claude Code write hook does not run in the view dir. On Linux, a write to an unpromoted repo fails with `EACCES` from the kernel; elsewhere only the worktree root loses its write bit. See [Limitations](/docs/reference/limitations).
- Projects work in the cloud against github.com. `ivar` runs locally. Hall, feature and session work with any git remote; pull requests go through `gh` and need GitHub.

## FAQ

### Does `--add-dir` give Claude Code a branch per repo?

Not documented. `--add-dir` grants file access. `ivar feature promote` creates the feature's branch and worktree in each repo you name.

### Can Claude Code use my CLAUDE.md from the other repos?

Only with `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1`. In an `ivar` session, the hall's `HALL.md` becomes the session's `CLAUDE.md`, so every repo shares one set of instructions.

### Do I need Projects?

No. Projects and `ivar` solve different problems: Projects run in the cloud, and `ivar` runs on your machine. Nothing stops you from using both.