Codeman maintainer
9c64fc128d
Every place that called the Codeman Agent Skill setting off by default now says it is on by default since 1.50.0, where to turn it off, and that turning it off still removes no copy already written (`codeman skill uninstall --case <name>` does). The README, the wiki's Codeman Skill page and the FAQ say an agent inside Codeman usually has the skill without an install step, and that the copy ignores itself in git. Also written down: an install whose App Settings were saved on an earlier version stored the old default and stays off until switched on; with the Claude Code plugin installed, Claude Code lists the skill twice (both work); and, in the invariants, the self-ignoring `.gitignore` rules and the measurement that Claude Code 2.1.319 never runs `git check-ignore` on a skill folder. The agent control plan keeps its original default-off decision and gains a dated note for the flip. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
5.2 KiB
Git Worktrees
Sessions in one case share its folder. That is fine for one agent, but three agents in the same checkout edit the same files, overwrite each other's builds, and commit each other's half-finished work. A git worktree gives each of them a checkout of its own: same repository, same history, a separate folder on a separate branch.
Codeman creates worktrees for a case whose folder is a git repository, starts sessions in them, and removes them again when the work is done.
Where they live
<case>/.claude/worktrees/<name>, on a new branch worktree-<name>. That is exactly where
Claude Code's own claude --worktree <name> puts them, so a worktree made in Codeman is one
Claude Code recognizes, and the other way round. Codeman's Recent Sessions and Session Manager
lists mark a session that runs in one with a ⑂ <name> pill.
The main checkout does not show the worktrees as untracked: Codeman adds /.claude/worktrees/
(and /.claude/settings.local.json, the hooks file it writes for every Claude session, plus the
codeman folder it writes while Codeman Agent Skill is on, the default) to the repository's local
.git/info/exclude when git does not ignore them already. Without that, those files would make
every worktree look modified and git would refuse to remove it. Your tracked .gitignore is
never touched.
Creating one and starting a session in it
- Pick the case in the toolbar's case picker.
- Open the picker again and choose Git worktrees… (on a phone: the case sheet's Worktrees button).
- Under New worktree, type a name (letters, digits,
.,_,-, up to 64 characters). - Pick the CLI under Start sessions with (Claude Code, Codex, a shell, any installed run mode).
- Create & start session.
The worktree is created from the case's current commit, and the session opens in it as a tab
named w1-<name>. Under Branch and start point you can name the branch yourself or start
from another branch, tag or commit. An existing branch is never reused or reset: pick another
name.
Open on a worktree's row starts another session in it, with the CLI chosen above.
When an agent moves into a worktree
Claude Code can move a running session into a worktree part way through (its EnterWorktree tool), and the session's tab stays on the case. While the session's pane is in a worktree inside the session's folder, the Files panel lists that worktree, so you see the files the agent is editing. A strip under the panel's title names the worktree, and its Session folder button switches to the session's own folder (Back to worktree returns). The panel follows the agent in and back out on its own while it is open.
Only the Files panel moves. The Git panel stays on the session's folder, so it can show
main while the strip names the worktree. And .claude is a hidden folder of the session's
folder, so an .html file in .claude/worktrees/<name> opens as source rather than as a
rendered page. A session started in the worktree does not have that limit.
A worktree outside the session's folder (git worktree add ../feature) is not followed: Codeman
only serves files inside the session's folder. The same goes for a session started in a subfolder
of the repository, because Claude Code puts the worktree at the top of the repository, which is
outside that session's folder. Open such a worktree as a case of its own with Add Case > Link
Existing.
Removing one
Two ways, and both use git worktree remove without --force:
- Remove… on the worktree's row in the dialog.
- Closing a session that runs in a worktree: the Close Session dialog offers Kill & remove worktree, which kills the session and then removes its worktree.
git refuses to remove a worktree that still holds uncommitted or untracked files, and Codeman shows that refusal as git worded it and leaves everything in place. Commit, stash or delete the work first, then remove again. A worktree a live session still runs in is refused too.
Also delete its branch deletes the branch with git branch -d, which keeps a branch whose
commits are not merged yet. The worktree is still removed, and the message says the branch was
kept.
If a worktree's folder was deleted by hand, its row says missing and offers only Remove…: that clears the record git keeps of it, so the name can be used for a new worktree.
What is not supported
- Docker cases and remote (SSH) cases. A container can write to its workspace, and creating a worktree runs the repository's hooks and checkout filters on the Codeman machine, so git is never run there. A remote case's repository is on another machine. For the same reason a worktree that a Docker case uses as its workspace (or that holds one) is never removed from here: remove the Docker case first.
- A case folder that is not the top of a repository (a subfolder of one), a bare repository, or an empty repository with no commit yet.
- Worktrees outside
.claude/worktrees/(made by hand withgit worktree add) are listed, but Codeman neither starts sessions in them from the dialog nor removes them.
The HTTP endpoints are in the HTTP API reference (/api/cases/:name/worktrees).