The context problem nobody solved: AI agents across multiple repos

Why one repo is the unit an agent understands

AI coding agents are fundamentally designed around a single root directory. When you initialize an agentic session—whether using Claude Code, Codex, Aider, or custom CLI execution harnesses—the harness binds directly to the process's current working directory (cwd).

Inside that single repository boundary, the agentic tooling architecture operates cleanly. The harness reads local instruction files such as CLAUDE.md, .cursorrules, or AGENTS.md, indexes the directory tree, connects to local Language Server Protocol (LSP) daemons for symbol resolution and type checking, runs test runners, and inspects git status. The context window is optimized to ingest and edit files relative to that single canonical root.

However, modern software engineering rarely lives within a single repository. Enterprise systems and modern cloud architectures are routinely split across polyrepo boundaries: a Rust core backend, a TypeScript frontend client, an OpenAPI contract repo, an infrastructure-as-code repository, and shared internal utility libraries.

When a developer asks an agent to perform a feature task that spans multiple repositories—such as updating a database schema, adjusting an API endpoint, and reflecting those contract changes in a web application—the single-repo architecture breaks down across several distinct vectors:

1. LSP and Symbol Resolution Failures: Language servers rely on explicit project configuration files (e.g., tsconfig.json, Cargo.toml, go.mod) located at recognized workspace roots. When an agent attempts to inspect code in a sibling directory outside its bound cwd, the LSP cannot resolve cross-repository types or jump-to-definition targets.
2. Context Window Noise and Index Pollution: Search utilities like grep or file tree crawlers executed by the harness default to searching relative to the active root. If forced to search higher up the filesystem tree, indexing algorithms ingest unrelated build artifacts, node_modules, target binaries, and lockfiles, quickly saturating the LLM context window with irrelevancies.
3. Git Semantics Breakdown: Git operations (git diff, git status, git commit) execute relative to the repository containing cwd. When an agent edits files in sibling repositories without changing execution directories, git commands fail or apply modifications to the wrong repository context.
4. Interactive Session Fragmentation: Switching execution directories dynamically within an active agent session resets tool state, loses chain-of-thought context, invalidates cached workspace maps, and frequently leads to agent hallucination regarding file locations.

Because the single repository remains the hard-coded unit of understanding for existing AI harnesses, engineers working across polyrepo architectures are forced to rely on fragile community workarounds.

The five workarounds people actually use

As agentic coding adoption has accelerated across engineering organizations, teams have attempted to bridge the cross-repo context gap. Based on developer surveys, community architecture guides, and technical discussions surrounding multi-repo AI workflows, five primary workarounds have emerged.

1. The Parent "Mega" Workspace Directory

The simplest and most common workaround is pointing the AI harness at a top-level parent folder containing all local repositories:

cd ~/projects
claude

In this layout, ~/projects/ acts as the root, placing ~/projects/backend-api, ~/projects/web-frontend, and ~/projects/shared-schema inside the agent's visible directory hierarchy.

Where it breaks: Git awareness collapses completely. The parent directory ~/projects is not itself a git repository. Standard harness commands like git status or git diff fail immediately with fatal: not a git repository. Furthermore, file search utilities scan across every cloned repository simultaneously, overloading context limits with irrelevant search hits, while language servers fail to establish root boundaries for auto-completion and type checking.

2. The Meta-Repository with Git Submodules

To restore git tracking at the workspace root, teams construct a meta-repository (often called a "repo-of-repos" or workspace wrapper) that links individual repos as git submodules:

/meta-workspace
 ├── .git/
 ├── .gitmodules
 ├── backend-api/     (submodule)
 └── web-frontend/    (submodule)

Where it breaks: Git submodules introduce heavy operational overhead and state desynchronization. Modifying code inside a submodule leaves the parent meta-repository in a modified state, requiring a multi-step commit dance (committing inside the submodule, then committing the updated submodule pointer in the meta-repo). Branching becomes particularly error-prone: checking out a feature branch in the meta-repo does not automatically check out matching branches inside submodules, causing submodules to enter a detached HEAD state and confusing the agent's mental model of branch alignment across services.

3. System Prompt & Relative Path Guidance

Another prevalent strategy relies on injecting explicit relative path directions into system prompts or repository instruction files (CLAUDE.md, .cursorrules, AGENTS.md):

# Multi-Repo Context Rules
- The backend API code is located at `../backend-api`.
- The shared OpenAPI schema is at `../shared-schema/openapi.json`.
- When updating frontend types, read `../shared-schema/openapi.json` first.

Where it breaks: Relying on relative path instructions places the entire burden of path resolution on the LLM's prompt compliance. Under high token loads or multi-step reasoning tasks, models non-deterministically violate relative path boundaries, attempt to write files outside allowed trees, or hallucinate relative directory levels (e.g., ../../backend-api). Additionally, relative paths break bash tool execution: commands run by the agent default to cwd, producing errors when build scripts or test runners expect to be executed from a sibling repository's root.

4. MCP (Model Context Protocol) Context Bridges

With the adoption of MCP, developers construct custom MCP servers that expose search, read, and indexing interfaces to external repositories. An agent operating within web-frontend calls an MCP tool to fetch function signatures or schema definitions from backend-api.

Where it breaks: MCP bridges provide tool-gated, read-only context retrieval. While an MCP server enables an agent to query code snippets from external repositories, it does not grant the agent the capability to perform native file edits, run local language servers, execute test suites, or manage git commits in the target repository. It solves snippet retrieval but leaves multi-repository execution completely unaddressed.

5. Server-Mediated Orchestration & Multi-Agent Swarms

For large-scale enterprise environments, organizations construct multi-agent server platforms. A centralized orchestrator agent receives an overall task specification, decomposes it into repository-specific sub-tasks, and dispatches individual agent instances to execute asynchronously against remote repositories via API calls.

Where it breaks: Server-mediated multi-agent swarms sacrifice the local, interactive developer-in-the-loop workflow. Communication between agents occurs via natural language summaries sent over network APIs, introducing significant latency, high token consumption, and compounding translation errors. When a multi-repo build fails, diagnosing which agent introduced the breaking change across asynchronous API boundaries is difficult and time-consuming.

What every workaround has in common

Evaluating these five approaches side-by-side reveals a fundamental structural pattern:

Every community workaround makes a fundamental trade-off between workspace visibility, execution capability, and write protection.

None of these approaches provides a real Git worktree on the same feature branch across multiple repositories with write access guarded deterministically at the filesystem layer.

They inevitably fall into one of three failure modes:

1. They compromise git semantics and language server integration by flattening repositories into plain directories or submodules.
2. They rely on soft, non-deterministic prompt rules or software hooks to control file writes, which fail under context pressure.
3. They isolate the agent so strictly (via read-only MCP tools or remote swarms) that the agent cannot perform coordinated edits or run cross-repository test suites.

What a view directory is

To overcome the single-repository limitation while preserving native git semantics and execution capabilities, workspace orchestration requires a dedicated abstraction layer: the View Directory (View Dir).

A View Directory is a materialized, session-specific workspace folder constructed dynamically for an agentic session. Rather than duplicating code or creating nested meta-repositories, a View Directory aggregates registered repositories using native operating system symlinks pointing directly to real Git worktrees.

When an agent session initializes within a View Directory:

1. Promoted Repositories: Repositories where active code modifications are planned are mounted as Git worktrees checked out on the exact same feature branch (e.g., feature-x).
2. Unpromoted Context Repositories: Repositories included solely for reference are mounted as Git worktrees checked out on their default branch (e.g., main).
3. Instruction Resolution: Provider-native instruction files (CLAUDE.md, AGENTS.md) at the root of the View Dir are dynamically synthesized from a canonical hall configuration (HALL.md), giving the agent unified multi-repo instructions without dirtying individual repository trees.

Because each entry inside a View Directory points to a genuine Git worktree, language servers process cross-repo imports seamlessly through symlinks, build utilities run locally, and git commands maintain total integrity. The concepts page covers the rest of the model.

Read access is not the hard part — write access is

Exposing multiple repositories for reading is trivial; any file crawler or MCP server can ingest text from sibling directories. The true technical challenge in polyrepo agentic development is enforcing strict write isolation.

When an AI agent operates inside a multi-repository workspace, language models frequently attempt unauthorized or out-of-scope file modifications. For example, while updating a frontend component to handle an API change, an agent might attempt to edit a shared library file to fix a lint error, accidentally mutating git state in a shared context repository.

Why Prompt-Based and Hook-Based Guards Fail

Traditional agent frameworks attempt to enforce write safety through soft boundaries:

• System Prompt Instructions: Advising the model "Do not modify files inside the /docs or /lib directory". As context windows fill and reasoning chains complexify, models non-deterministically ignore prompt constraints.
• PreToolUse Hooks: Intercepting file-writing tool invocations in software. Hooks add execution latency, are tied to specific harness implementations, and fail to prevent writes executed via raw shell commands (such as echo, sed, or build script output redirection).

POSIX Filesystem Guarding (chmod)

To guarantee absolute safety, write protection must operate below the LLM layer, enforced deterministically by the operating system kernel.

In ivar, write safety is enforced at the POSIX filesystem level using file permission masks (chmod). Unpromoted context repositories mounted inside a View Directory are stripped of write bits across their entire worktree tree:

if mode & 0o222 != 0 {
    chmod(path, mode & !0o222)?;
}

When an unpromoted repository is mounted:

1. clear_write_bits applies mode & !0o222 recursively to every file and folder in the repository's worktree.
2. If an agent attempts to modify a file in an unpromoted repository—whether using a file edit tool, a bash command redirection, or an automated refactoring script—the OS kernel immediately halts the operation with a deterministic EACCES (Permission Denied) error.
3. Neither LLM prompt compliance nor harness hook logic is involved in blocking the write; enforcement occurs directly at the kernel boundary.

When a repository is explicitly promoted to active edit status within the session, restore_write_bits selectively re-enables write permissions (u+w), permitting authorized edits:

chmod(path, mode | 0o200)?;

This deterministic mechanism guarantees that read-only context repositories remain strictly immutable throughout the agentic session, regardless of model behavior or shell execution.

Where this leaves you

The single-repository constraint has hindered polyrepo agentic development. While community workarounds—from mega-directories to custom MCP servers—have provided temporary stopgaps, none provide a workspace environment that combines native git execution, multi-repo visibility, and deterministic write protection.

The View Directory pattern replaces soft prompt boundaries and artificial folder structures with a kernel-enforced, worktree-native workspace primitive. OS-enforced permission masks ensure read-only stability across context repositories, while genuine Git worktrees preserve complete compatibility with local development tools and AI harnesses.

The mechanism behind View Dirs, and the vocabulary it uses, is covered in what a View Dir is and why it exists. To mount your own repositories into one, start with the quickstart.