How-to Guides

Run multiple AI coding agents in one repository

Run multiple AI coding agents in one repository by giving each task its own Kalauz workspace. Each workspace is an isolated git worktree and branch, so three to five agents can work in parallel while you review each diff in place.

That is the useful range for most teams: enough parallelism to keep work moving, but still few enough that an experienced developer can read the changes, run tests, and merge intentionally.

1. Start from one repo

Add the repository once, then create a separate New workspace for each task. Kalauz creates every workspace as its own branch plus git worktree, outside your main checkout. The agents do not share a working directory, so one task cannot overwrite another task's uncommitted files.

If you need the exact git mapping, see Isolated workspaces.

2. Split the work into agent-sized tasks

Give each workspace a narrow task with clear acceptance criteria. Good parallel work is usually independent: one agent fixes a bug, another updates a component, another writes a migration, and another adds tests around a known behavior.

Avoid sending two agents into the same files for vague exploratory work. Worktree isolation prevents local file races, but it does not remove the review burden or the need to reconcile overlapping branches later.

Workspace A: Fix the pricing table mobile overflow. Add a layout test if one exists.
Workspace B: Add empty-state copy to the imports page. Keep behavior unchanged.
Workspace C: Update the webhook retry test to cover exponential backoff.

For tasks where you want the approach before edits, use Plan mode.

3. Use profiles when context should stay separate

Profiles separate the operational defaults an agent runs with: credentials, git identity, model provider, and privacy defaults. Use them when the same machine works across different accounts, repositories, providers, or policy boundaries.

The active profile also controls the worktrees root and the git identity applied to each workspace's local config. Provider defaults and CLI credentials are passed into agent runs from that profile, then combined with project and managed settings. See Configure model providers and Agent behavior for the launch details.

4. Keep three to five agents active

Kalauz does not require a separate clone per agent. Because workspaces are git worktrees, you can keep several branches checked out against the same repository without stashing or hand-copying directories.

In practice, three to five parallel agents is the useful range. Below that, the workflow is mostly sequential. Above that, review usually becomes the bottleneck: you still need to inspect diffs, run the right commands, and decide what lands. For the broader concurrency model, see Parallel agents.

5. Review each diff where it was produced

When an agent settles, open the workspace's Diff tab. Kalauz shows the change set against the base branch in place, so you can review the files without leaving the workspace. Add inline comments, send them back to the agent, and run the repo's test or run command from that workspace before opening a PR.

The important habit is to merge small, finished branches regularly. Each agent can move independently, but your base branch should not become a pile of stale worktrees waiting for one large review pass. See Review and merge a workspace for the shipping flow.

What's next?