worktrees

kasmos runs each agent instance in an isolated git worktree — a separate working directory checked out from the same repository. This lets many agents work concurrently on different branches without stepping on each other.

why worktrees

If multiple agents worked in the same directory, they would conflict at the filesystem level: editing the same files, running tests that race, or committing to the same branch. Worktrees give each agent its own isolated workspace while sharing the full git history.

worktree location

All worktrees live under the main repository root in a .worktrees/ directory:

<repo-root>/
├── .git/             ← main repository
├── .kasmos/          ← repo-local config and runtime state
├── .worktrees/
│   ├── kas/feature-a_1718000000000000/   ← agent 1
│   └── kas/feature-b_1718000000000001/   ← agent 2
└── ...

Each worktree directory name is <branch-prefix><session-name>_<unix-nano> to avoid collisions when agents are restarted.

config anchoring and the task store

kasmos separates two kinds of state:

• repo-local runtime state lives under <repo-root>/.kasmos/: config.toml, signal files, cache, and worktree checkout metadata. This state is specific to the repository.
• the task store (~/.config/kasmos/taskstore.db) is a single global SQLite database shared across all projects on the machine. All worktrees and all concurrent agents read and write the same database, which is how the daemon and parallel coders coordinate.

config.GetConfigDir() resolves the main repo root even when called from inside a git worktree (where .git is a file rather than a directory), so all worktrees share the same repo-local config while still pointing at the same global task store.

creating a worktree

When an agent is launched, kasmos creates the worktree:

1. a branch name is generated from the configured branch prefix and session name, sanitized, and given a unique path under .worktrees/.
2. git worktree add -b <branch> <path> creates the worktree on disk.
3. the instance stores the worktree path and branch name so it can be restored later.

To use an existing branch, kasmos accepts an explicit branch name and skips generation.

checkout flow

When you press c in the TUI on a running instance:

1. the instance is paused (agent process killed; branch preserved).
2. the branch name is copied to the clipboard.
3. kasmos shows a help screen explaining how to check out the branch in your main working tree.

You can then git checkout <branch> or open the branch in your editor to inspect and continue the work.

resume flow

When you resume a paused instance:

1. Resume() calls Start() again.
2. the execution session (tmux or headless) is recreated from the stored execution mode, program, and worktree path.
3. the agent restarts inside the same worktree, with the same branch, and can pick up where it left off.

orphan adoption

Tmux sessions that existed before kasmos was started — or whose kasmos instances were lost — are called orphaned sessions. Press T in the TUI to browse them. kasmos shows which tmux pane names look like agent sessions and lets you adopt them as tracked instances.

Orphan adoption reconstructs a minimal instance from the tmux session metadata so kasmos can track its status, pause it cleanly, and associate it with a task file.

shared worktree safety (for agents)

When KASMOS_TASK or KASMOS_PEERS is set, multiple agents are working in the same worktree (wave parallelism). Each agent is assigned non-overlapping files by the architect metadata. Key rules:

• Never git add . or git add -A — only add your assigned files
• Never run formatters across the whole project
• Never git stash, git reset, or git checkout -- <file> on files you didn't create

These constraints are injected into the agent's prompt by the orchestration layer.