Monorepos

Run agents against a monorepo that holds many packages or apps.

A monorepo is a single git repository that contains several packages or applications. In Kalauz you add the repo once, at its root, and every workspace gets a worktree of the whole tree.

Add the root, once

Add the monorepo's root folder as a single project. Because a workspace is a git worktree of the entire repository, an agent in any workspace can see and change any package — which is exactly what you want for changes that cross package boundaries.

Setup and run scripts

Environment detection looks at the root, so it keys off whatever lives there — often a root package.json with a workspaces field. Point the setup and run scripts at your monorepo tooling:

# Setup: install everything from the root
pnpm install

# Run: scope to a package, or run a workspace task
pnpm --filter @acme/web dev

For repo-wide consistency, check a kalauz.json into the root with the right scripts.setup and scripts.run so every teammate's workspaces behave the same — see Testing.

Scoping a workspace to one package

There's no separate per-package project — the workspace spans the whole repo. Scope the work instead: tell the agent which package to focus on, and point the Run script at that package. The blast radius is still contained, because the whole thing lives on its own branch and worktree.

What's next?

• Multiple repositories — when your code is split across repos instead.
• Testing — tuning setup and run scripts.