Isolate work in a worktree
Several sessions in one checkout overwrite each other and contend for git's index. A worktree is one directory + one branch per task, sharing the repository.
This session does not move. worktree(action="new") returns a path.
Pass that path as work_dir on read_file / write_file / apply_patch /
execute. On glob / grep, pass it as path. Omit those arguments and
the call stays in this session's directory.
Do not cd and expect later calls to follow — each call is independent.
Do not execute git worktree add: that only makes a directory, and later
calls still use this session unless you pass work_dir / path. Use
worktree(action="new").
When
list_agentsshows another session in this directory (dirty files, same branch) and you are about to edit.- A change should not land on the shared working tree.
Not this: a read-only task subagent (it does not write). A second CLI
that should start already inside a tree is agentica --worktree <task>.
How
Name the task, not yourself. Reused while the checkout is healthy; gone after merge. A registration that is no longer a checkout is refused — remove it first, or pick another name. The tool does not delete leftover files to make room.
worktree(action="new", name="<task>")— create or reuse; returns the pathworktree(action="status")— every worktree of this repoworktree(action="merge", name="<task>")— land on local main (conflicts stay in that worktree, then fast-forward on main), delete the checkoutworktree(action="remove", name="<task>")— drop awt/*checkout git will allow (dirty is refused; an unmerged branch is left in place)
new(name="main") is refused: main is the repository root, not a task.
For a chunk of work big enough for its own process, delegate(task=..., work_dir=<path>) already takes the same path.
If a directory goes missing, status labels it (directory gone) or
(not a checkout). Say so; do not rebuild it by destroying what sits there.
remove the name, then new if you still want it.
