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), fromorigin/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
.venvfolders keep the old path, andmake testfails withFailed 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 ofgit -C <worktree> ...segments orcd <worktree>followed bygitsegments;.claude/hooks/guard-mainchecks 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 -2is judged by<branch>, whatever pipe or chain surrounds it; it is refused only when it namesmain(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 wordcommitin a worktree slug too:claude-guard-main-clonerefusedscripts/worktree/new docs <id>-...-commit-.... Four tries failed this way on 2026-10-29 before the plain form passed. - Text that names
nereus initgoes in a file, through the Write tool: in a heredoc,.claude/hooks/guard-kept-clustercannot read the command and refuses it, even when nothing runs on a cluster (#827, twice).