agentleFS
Sign inStart free
vrodokanakisvrodokanakis/claude-skills/worktree-space/SKILL.md

worktree-space

Skill0 starsChanged 2 months agoMITView on GitHub

Use when running inside Herdr (HERDR_ENV=1) and the user asks to open a worktree in a Herdr space, move this session into a new worktree, start feature work in its own worktree workspace, or says worktree space / herdr worktree / open in herdr. Works in any git repository. Outside Herdr do not use it: use EnterWorktree alone.

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Create the worktree with the bundled script, then move this session into it with EnterWorktree.

    line 8
  2. Very specific:

    Call EnterWorktree with the printed path.

    line 37
  3. Distinctive:

    If the script reported a background setup log, wait for it before any command that needs dependencies or databases:

    line 39
  4. Very specific:

    After moving from one worktree to another, the previous worktree is no longer writable from this session.

    line 60

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Worktree space

Create the worktree with the bundled script, then move this session into it with EnterWorktree. The script moves the terminal pane into a grouped Herdr workspace; EnterWorktree moves the session. Both are needed, and the script cannot do the second one.

Worktrees go under <repo>/.claude/worktrees/<slug>. That is the one location EnterWorktree accepts from anywhere, including from a session already sitting in another worktree, so chained runs are a normal move.

Script: ~/.claude/skills/worktree-space/scripts/worktree-space.sh (--help is the header comment; read it for flags).

Steps

  1. Gate: test "${HERDR_ENV:-}" = 1. If it fails, say so and stop using this skill. Create the worktree with EnterWorktree name=<slug> instead.
  2. Pick the branch name up front (the ticket's canonical branch name if the project uses one; renaming a branch with an open PR closes the PR).

  3. Run:

    ~/.claude/skills/worktree-space/scripts/worktree-space.sh <branch>

    It prints the worktree path, the workspace id, and a final ==> Next: EnterWorktree path="..." line. If the repo ships its own bin/worktree-herdr, the script delegates to it and the project's own worktree skill or AGENTS.md rules take over from here, including any handoff behaviour on chained runs.

  4. Call EnterWorktree with the printed path. Never claude --resume in the new workspace: the running session is the one that moved.

  5. If the script reported a background setup log, wait for it before any command that needs dependencies or databases:

    grep -q 'Done. Worktree ready' <repo>/.claude/worktrees/<slug>-setup.log
  6. First report after the move states: workspace opened, session moved, and whether setup is still running.

Project hooks

  • bin/worktree-herdr in the repo: the script execs it. Project owns the flow.
  • .claude/worktree-setup.sh in the repo (executable): run once inside the new worktree in the background with args <slug> <branch>. Its last line on success must be Done. Worktree ready. Use it for bundle/db/deps.

Notes

  • Re-runnable: an existing worktree dir is reused and an already-open workspace gets a new tab instead of a second workspace.
  • After moving from one worktree to another, the previous worktree is no longer writable from this session. Re-enter it with EnterWorktree path if you need to.
  • Teardown: ExitWorktree moves the session back, not the pane. Move the pane to its home workspace first (herdr pane move <id> --workspace <home>), then exit with action: "remove". The empty workspace closes when its last pane leaves. Delete the setup log too.
  • Outside Herdr the script still builds the worktree and prints the herdr worktree open command to run later.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free