# Monorepos

<a id="why-monorepos-benefit-from-panes-worktree-model"></a>

Give each package its own [pane](/docs/panes-and-worktrees), so one agent rewrites `packages/api` while another works on `packages/web`, each on its own branch.

> **Warning:** Worktrees keep files apart while agents work. If two agents both edit `packages/shared`, you'll resolve the conflict when you merge. Give each agent one package.

```
my-monorepo/                    ← your main checkout
my-monorepo/worktrees/api/      ← pane on feature/api-rewrite
my-monorepo/worktrees/web/      ← pane on feature/web-refresh
```

<a id="setup-one-pane-per-package"></a>

## Set it up

1. Add a [`pane.json`](/docs/configuration) so every new pane installs dependencies. `pane.json` has one `run` script for the whole repo, so leave `run` out and start each package's dev server yourself:

   ```json
   { "scripts": { "setup": "pnpm install --frozen-lockfile" } }
   ```

2. Click **+** on the repo to create a pane per package.
3. In each pane, open a terminal tab from **+**. It starts at the worktree root. Start the agent inside the package, and the dev server in another tab:

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

   ```bash
   PORT=$PANE_PORT pnpm --filter api dev
   ```

<a id="avoiding-cross-package-conflicts"></a>

### Keep each agent in its package

Add a `CLAUDE.md` (or `AGENTS.md` for Codex) in each package:

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

Claude Code reads `CLAUDE.md` from the folder you start it in and each folder above it.

### When a worktree is too heavy

To run a pane in your main checkout instead, open **Advanced** in the **New Pane** dialog and turn off **Use worktree**. There's no isolation there, so run one agent at a time.

## Nx

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

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

Each worktree is its own Nx workspace, so the Nx daemon runs once per worktree. See [nx.dev/docs](https://nx.dev/docs).

## Turborepo

`--filter` runs a task for one package. The `...` suffix adds its dependencies:

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

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

## pnpm workspaces

`pnpm install` in each worktree links packages from pnpm's shared store, which saves space. Each worktree still has its own `node_modules` layout. Generated files, like build output, take extra disk space in every worktree. So do copied files, with one exception: on macOS (APFS), Pane clones copied folders, so they share disk space until they change. Single copied files are full copies.

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

Pane also copies `node_modules` into each new worktree ([file sync](/docs/configuration#worktree-file-sync)), so packages are there right away. Your `setup` install then updates them to the branch's lockfile. See [pnpm.io/workspaces](https://pnpm.io/workspaces).

## Related

- [MCP servers](/docs/mcp): give monorepo agents access to Linear, Jira, or internal tools
