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.
Everything the harness does well stops at the edge of the directory it was pointed at.
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:
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.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.git diff, git status, git commit) execute relative to the repository containing 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.
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.
| Workaround | What it does |
|---|---|
| Parent workspace directory | Opens ~/projects/ as the agent root |
| Meta-repository | A parent repo with the others as submodules |
| Prompt and path hacks | Injects ../repo-b into the instruction file |
| MCP context bridge | Exposes the other repos as read-only search tools |
| Server-mediated orchestration | Hands the work to agents behind an API |
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, over context limits with irrelevant search hits, while language servers fail to establish root boundaries for auto-completion and type checking.
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.
Another prevalent strategy relies on injecting explicit relative path directions into system prompts or repository instruction files (CLAUDE.md, .cursorrules, AGENTS.md):
- 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.
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.
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.
Evaluating these five approaches side-by-side reveals a fundamental structural pattern:
| Workaround Strategy | Git Integration | Local Test Execution | Write Protection | Operational Friction |
|---|---|---|---|---|
| Parent Workspace Dir | Broken ( not a git repo ) |
Unreliable | Unprotected | Low |
| Meta-Repo / Submodules | Complex (Detached HEAD) | Local only | Unprotected | High |
| Prompt Path Hacks | Single repo only | Fails on relative paths | Soft / Prompt-based | Low |
| MCP Context Bridge | None (Tool abstraction) | None (Read-only) | Read-only | Medium |
| Multi-Agent Swarms | Isolated per agent | Asynchronous / Remote | Isolated per agent | Very High |
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:
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.
Each entry is a symlink to a real worktree. Promotion decides which of them the kernel will let the agent write to.
When an agent session initializes within a View Directory:
feature-x). main). 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.
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.
Traditional agent frameworks attempt to enforce write safety through soft boundaries:
"Do not modify files inside the /docs or /lib directory". As context windows fill and reasoning chains complexify, models non-deterministically ignore prompt constraints.echo, sed, or build script output redirection). 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:
clear_write_bits applies mode & !0o222 recursively to every file and folder in the repository's worktree.EACCES (Permission Denied) error.
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.
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.