# Monorepos

Monorepos are where Pane really shines, but also where things can go wrong. The good: agents can work on independent packages in parallel. The bad: agents in different panes might edit the same shared code. The fix is simple: one pane per package, and scope each agent to its package.

## Why monorepos benefit from Pane's worktree model

Git worktrees give each pane its own working directory pointing at the same underlying repository. Three agents can work on `packages/api`, `packages/web`, and `packages/shared` in parallel without touching the same files. Each pane has its own branch, its own uncommitted changes, and its own shell state.

```
my-monorepo/                    ← main branch (read-only while agents work)
my-monorepo/worktrees/api/      ← worktree: feature/api-rewrite
my-monorepo/worktrees/web/      ← worktree: feature/web-refresh
my-monorepo/worktrees/shared/   ← worktree: feature/shared-types
```

## Setup: one pane per package

Pane creates worktrees automatically when you click **+** to add a pane. For manual control or CI use:

```bash
git worktree add ../api-pane feature/api-rewrite
```

Open `../api-pane` as the root in a Pane terminal. Then scope the agent to the package you care about by setting its working directory or passing the package path as context:

```bash
cd packages/api
claude
```

If you start your agent from the repo root, it sees the whole monorepo. Start it from inside `packages/api` instead and it'll focus on that package, less likely to wander into unrelated code.

## Nx

Run `nx affected` from the pane's worktree shell to build and test only the packages touched by the current branch:

```bash
nx affected --target=build
nx affected --target=test
```

Each pane's worktree has its own branch, so `nx affected` computes the diff independently per pane. You can run an `nx daemon` per worktree if you want the cache warm before the agent starts.

See [nx.dev/docs](https://nx.dev/docs) for full affected configuration.

## Turborepo

`turbo run build --filter=...` scopes a build to one package and its dependencies. Use it to keep agent runs from triggering unrelated package builds:

```bash
turbo run build --filter=@my-org/api
turbo run test  --filter=@my-org/api...
```

The `...` suffix includes dependencies. Drop it if you only want the package itself.

See [turbo.build/docs](https://turbo.build/docs) for filter syntax.

## pnpm workspaces

`pnpm install` in each worktree shares the underlying package store via pnpm's content-addressable cache. You do not get duplicate `node_modules` disk usage across panes.

```bash
pnpm install           # installs in the current worktree
pnpm --filter api dev  # run dev server for one package
```

See [pnpm.io/workspaces](https://pnpm.io/workspaces) for workspace protocol and filtering.

## Avoiding cross-package conflicts

Scope each pane's agent to its package by adding a `CLAUDE.md` at the package level:

```
packages/
  api/
    CLAUDE.md    ← "Only edit files under packages/api."
  web/
    CLAUDE.md    ← "Only edit files under packages/web."
```

Start `claude` from inside the package directory. Claude Code reads the nearest `CLAUDE.md` upward from the working directory, so the package-level file takes precedence.

## Related

- [Panes & Worktrees](/docs/panes-and-worktrees) — how worktrees work in Pane
- [MCP servers](/docs/mcp) — give monorepo agents access to Linear, Jira, or internal tools