Git worktrees

Run an agent in its own git worktree instead of your checkout. Several agents can then work on the same repository at once without touching each other's files, or yours. Worktrees work with both the native and the Docker sandbox backend.

stashbase agent run --profile coding --worktree -- claude

To make it the default for a profile:

[workspace]
worktree = true

Pass --worktree=false to skip the worktree for a single run.

How a run is laid out

Each run gets a readable name such as amber-river-storm:

• Worktree: .stashbase/worktrees/amber-river-storm inside the repository. It is visible in your IDE and hidden from git status.
• Branch: stashbase/amber-river-storm, started from whatever you have checked out.

The agent's working directory is the worktree, so its edits and commits never land in your checkout.

Review, merge, and clean up

Everything below happens locally. Nothing is pushed.

stashbase agent worktrees list                       # status and commits not merged yet
stashbase agent worktrees merge amber-river-storm    # git's own merge message
stashbase agent worktrees clean                      # remove merged agent work
stashbase agent worktrees remove amber-river-storm   # discard one run

merge refuses while there are uncommitted changes and stops on conflicts without losing anything.

Continue a run

Resume a previous run by name:

stashbase agent run --profile coding --resume amber-river-storm -- claude

Stashbase reuses the worktree if it was kept, including uncommitted work, or recreates it from the run's branch.

Safety

• Docker backend: the container sees only the agent's worktree and the repository's .git, never your checkout. Git config, hooks, submodule configs, your checkout's HEAD and index, and the worktree's own config are read-only.
• Native backend: the same git files and the rest of your checkout are added to the run's deny_write.
• After every run, Stashbase restores the worktree's git pointer files, restores deleted branches and tags, and resets rewritten ones. Commits and branches the agent created during the run are kept, with a warning listing them.
• Locking: a worktree is locked while a run is in progress, so merge, clean, remove, and plain git worktree remove never delete one under a working agent. Leftovers from killed runs are verified before any git command runs in them, and shown as UNSAFE if anything looks tampered with.

Limitations

• Docker-backend worktrees are not supported on Windows yet. Such a profile fails validation with a clear message.
• The agent can write the repository's shared object store, because it needs to in order to commit. This is the same as in runs without a worktree.
• With the native backend, the agent can still create new top-level files in your checkout, but not modify existing ones.

Next steps

• Filesystem restrictions
• Docker sandbox
• stashbase agent CLI reference