Git Worktrees
Spawn heroes in different git worktrees.
Git worktrees let you have multiple working directories for the same repository. AgentCraft supports this by scanning sessions from all worktrees, displaying worktree info in the UI, and letting you spawn heroes in specific worktrees.
Multi-Repository Workspaces
AgentCraft 0.5.0 can also start from a parent directory that is not itself a Git repository:
cd ~/projects
npx @idosal/agentcraftIt discovers nested Git repositories up to three levels deep while skipping dependency, build, cache, and hidden environment directories. The Spawn Options working-directory list shows each repository and branch. Select a repository before spawning; you can then create a worktree from that selected repository when needed.
Spawning in a Worktree
Press Q with the Town Hall selected to open Spawn Options. Choose the target repository or worktree under Working Directory before spawning.
Automatic Detection
AgentCraft detects git worktrees automatically at startup by running git worktree list. Sessions from all worktrees appear in the hero roster, each tagged with their source worktree.
UI Indicators
- InfoPanel — When a hero is selected, the info panel shows which worktree it's working in
- HeroRoster — The roster tooltip includes the worktree name
- Each worktree has its own project identifier, so sessions are naturally separated
Refreshing Worktrees
If you create a new worktree outside AgentCraft after starting the server, refresh the worktree list without restarting:
curl -X POST http://localhost:2468/admin/refresh-worktreesHow It Works
Claude Code stores sessions in ~/.claude/projects/{projectIdentifier}/ where projectIdentifier is the path with slashes replaced by dashes. Each worktree has its own project identifier, so sessions are naturally separated.
The SessionScanner caches worktree paths on construction and scans session directories for each worktree. Sessions are tagged with their source worktree path, which is propagated to the frontend via the session_roster WebSocket event.
Spawn Validation
When spawning an internal hero with a workingDir parameter, the path is validated against known worktrees. Invalid paths are rejected to prevent spawning heroes in arbitrary directories.