Worktrees

Kavi uses git worktrees to give each agent its own isolated working directory. This prevents agents from stepping on each other's changes and enables independent, parallel development.

Dual Worktree Model

Each Kavi session creates two agent worktrees alongside your main working directory:

Your main working directory remains untouched. Each agent operates in its own isolated worktree under .kavi/worktrees/.

Each worktree is a full checkout of your repository at a specific commit, with its own working directory and index. Agents read and write files in their respective worktrees without affecting each other or your main directory.

Isolation Guarantees

Worktree isolation provides several guarantees:

• No cross-contamination -- changes made by Codex never appear in Claude's working directory, and vice versa
• Independent staging -- each agent has its own git index for staging changes
• Safe experimentation -- agents can make speculative changes without risking the main branch
• Parallel execution -- both agents can modify files simultaneously without merge conflicts during development

Independent Commits

Each agent commits directly to its worktree. These commits are real git commits on temporary branches:

main ─── A ─── B ─── C
                │
                ├── codex/session-xxxx ─── D ─── E
                │
                └── claude/session-xxxx ─── F ─── G

Commits happen automatically as agents complete units of work. Each commit captures:

• The changes made by the agent
• A descriptive commit message generated by the agent
• The task ID that produced the changes

Diff Tracking

Kavi tracks diffs between each worktree's current state and the base commit (the point where the worktree branched from your target branch). This provides:

• Progress visibility -- see what each agent has changed relative to the starting point
• Review material -- diffs feed into the review system for disposition
• Conflict detection -- overlapping changes between worktrees are identified early
• Landing preparation -- the integration process knows exactly what needs to be merged

You can view per-agent diffs in the TUI at any time during a session.

Snapshot Commits

Before integration, Kavi creates snapshot commits of any uncommitted changes in agent worktrees. This ensures that no work is lost during the landing process, even if an agent has pending modifications that haven't been committed yet.

The snapshot process:

1. Check each agent worktree for uncommitted changes
2. Stage and commit any dirty state with a snapshot marker
3. Record the snapshot commit hash in the session log
4. Proceed to integration with a clean state

Worktree Lifecycle

Worktrees follow the session lifecycle:

1. Creation -- when a session starts, Kavi creates worktrees for each agent branching from the configured base_branch
2. Active use -- agents read and write files, make commits, and track diffs
3. Integration -- changes from both worktrees are merged in the integration worktree
4. Cleanup -- after successful landing, agent worktrees are removed

If a session is interrupted and resumed, existing worktrees are reused rather than recreated.

Base Commit

The base commit is the commit on your target branch from which agent worktrees branch. It is recorded at session start and used for:

• Computing diffs (what changed since we started)
• Detecting upstream changes (has the target branch moved?)
• Determining merge strategy during landing

The base branch is configured in your project config:

base_branch = "main"