Use Claude Code with multiple repositories

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) 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, 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, accessed 2026-10-06).

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

Install and create a hall

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 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.

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:

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.

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.

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.
• 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.