One repository. Separate working worlds.

Branches alone do not isolate processes.

A branch records a line of development. A worktree provides the physical directory in which a process reads and writes that branch. If two agents use the same directory, checking out different branches is sequential and unsafe: one process can change the files beneath the other.

With separate worktrees, Agent A can build authentication in one folder while Agent B works on notifications in another. Both folders share the repository history, but their checked-out files, indexes, and active branches are separate.

The manual pattern.

From the primary checkout, update the base branch and create one branch-backed worktree for each independent task:

git fetch origin
git worktree add ../worktrees/auth -b agent/auth origin/main
git worktree add ../worktrees/notifications -b agent/notifications origin/main

# Run each agent in its assigned directory
cd ../worktrees/auth
claude

cd ../worktrees/notifications
codex

When an agent finishes, inspect its branch from inside that worktree. Commit only the intended files, run the relevant tests, and compare the full branch against the current integration branch.

git status --short
git diff --stat origin/main...HEAD
git diff origin/main...HEAD

# After review and integration
git worktree remove ../worktrees/auth
git branch -d agent/auth

Worktrees prevent overwrites, not logical conflicts.

Two agents can safely edit their own folders and still produce branches that conflict when merged. They may change the same interface differently, rely on incompatible assumptions, or independently modify a migration sequence.

• Shared dependencies: package caches can be shared, but each worktree may still need its own installed dependency tree or setup command.
• Ignored secrets: files such as .env are not created automatically in a new worktree. Decide whether to copy, link, or regenerate them without committing secrets.
• Ports and services: parallel applications can collide on localhost ports, databases, or external test accounts even when source files are isolated.
• Base drift: a long-running worktree can fall behind main. Sync deliberately and re-run tests after integration.

A safe worktree lifecycle.

1. Create from a known base. Record the starting branch and commit so the resulting diff has an unambiguous baseline.
2. Prepare the environment. Make required configuration and dependencies available without leaking machine-specific files into commits.
3. Run one owned task. Keep the task boundary narrow and avoid pulling unrelated work into the branch.
4. Verify and review. Inspect status, diff, commits, and tests. A clean worktree is not evidence that the implementation is correct.
5. Integrate, then clean up. Merge in dependency order, test the combined result, retain a rollback path, and remove stale worktrees and branches.

What PapAgent automates.

PapAgent connects the worktree lifecycle to a Kanban card. It creates isolated task workspaces, launches the assigned native CLI in the right directory, records the run, exposes the resulting diff for review, and supports intentional merge or undo actions.

The important part is not hiding Git. It is keeping task state and Git state connected, so an agent run has a visible owner, branch, worktree, output, and review decision.

To decide which cards belong in separate worktrees, read Parallel AI coding without parallel chaos.