Skip to content

Worktrees

Every change on getnereus/nereus is made in its own git worktree (the owner, 2026-10-26, #447). A session may have its home in the main clone, one per tmux window, but the main clone is only read and pulled: it stays on main, for the owner, the docs server and the beach watcher (the owner, 2026-10-29). On the owner's machines a PreToolUse hook outside this repository, claude-guard-main-clone, refuses commits and file edits in the main clone, except files git ignores.

The session prompt follows the agent, not the worktree (#1239): the global session-prompt keeps one per agent name in the main clone's git folder, .git/session-prompts/<agent name>.md, loaded by the global SessionStart hook after /clear (#1953). The cycle: Session prompt.

  • One worktree per order or run, next to the main clone: ../nereus-<id>-<slug>, where <id> is the beach order id (20261026-1748) or, for a run without an order, the issue number (447), and <slug> says what the work is about. Example: ../nereus-20261026-1748-release-reef.
  • The branch carries the same name: <type>/<id>-<slug> (feat/20261026-1748-release-reef), from origin/main.
  • Create it: scripts/worktree/new <type> <id>-<slug> prints the path; work, commit and push from there.
  • Remove it after the merge, or when the order closes: scripts/worktree/remove <id>-<slug> refuses uncommitted changes and deletes the local branch once its pull request is merged or closed.
  • Do not move a worktree after a build: its .venv folders keep the old path, and make test fails with Failed to spawn: pytest. If you must, delete them and build again (#905).
  • A subagent gets its own worktree through isolation: "worktree" (as the glossary subagent does, Layout).
  • Say where the change lives (owner, 2026-11-18, #1868): in the first reply after creating a worktree, give its absolute path and say the main clone stays untouched. A session's shell returns to the main clone after each call ("Shell cwd was reset to ..."), which reads as if the change were made there, and changes another session's release leaves in the main clone look like yours.
  • Committing from a session that sits in the main clone: aim the whole command at the worktree, as one && chain of git -C <worktree> ... segments or cd <worktree> followed by git segments; .claude/hooks/guard-main checks the session's own branch otherwise (#346).
  • A push that names its branch passes from the main clone (#698): git -C <worktree> push --set-upstream origin <branch> 2>&1 | tail -2 is judged by <branch>, whatever pipe or chain surrounds it; it is refused only when it names main (origin main, HEAD:main). A push with no literal branch (git push, HEAD, --all, a $ in the name) is still checked against the session's branch, and quoted text (an issue or PR body that mentions a push) is not read as a command. Commits keep the plain-command rule below.
  • The guards read the command as text, so keep it plain: one line, the worktree as a literal absolute path (never "$w": neither guard expands a variable), and no $, ;, |, backticks, parentheses, redirections, heredoc or newline anywhere in it. Write the message to a file first: git -C /abs/worktree add --all && git -C /abs/worktree commit --file /abs/message.txt. The same applies to a commit in another repository's worktree (~/git/linux-...). Avoid the word commit in a worktree slug too: claude-guard-main-clone refused scripts/worktree/new docs <id>-...-commit-.... Four tries failed this way on 2026-10-29 before the plain form passed.
  • Text that names nereus init goes in a file, through the Write tool: in a heredoc, .claude/hooks/guard-kept-cluster cannot read the command and refuses it, even when nothing runs on a cluster (#827, twice).