agentleFS
0xfurai0xfurai/peekaping/.agents/skills/treehouse/SKILL.md

treehouse

Skill1.2k starsChanged 16 days agoMITView on GitHub

Work in isolated, reusable git worktrees with the `treehouse` CLI (github.com/kunchenguid/treehouse). Use when the user mentions treehouse, asks to do a task in an isolated worktree or sandbox checkout, wants several agents or subagents working on the same repo in parallel without conflicts, or wants to check, return, lease, prune, or destroy pooled worktrees.

  • Pipes a download into a shell
  • Reads credentials
  • Installs packages

3 other projects use a version of this.

Trending

More talk lately.thin dataabout the whole repository

Dec 2025: 0 mentionsJan 2026: 0 mentionsFeb 2026: 0 mentionsMar 2026: 0 mentionsApr 2026: 0 mentionsMay 2026: 0 mentionsJun 2026: 0 mentionsJul 2026: 0 mentionsAug 2026: 0 mentionsSep 2026: 0 mentionsOct 2026: 1 mentionNov 2026: 0 mentions
Dec 2025Jun 2026Nov 2026
Mentions a month of the 0xfurai/peekaping repository that our weekly crawl found: only 2 in all, so this is a hint, not a trend. There is no adoption data for this file yet.

Most recently taken up by

  • Other versions3 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 3

    1. DetachHead/rebased★ 6.5ksame name
    2. yahyabedirhan/skills★ 3same name
    3. vipentti/skills★ 1same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository8 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

6 rules. 0 are common, 3 are distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 3 edited versions we read keep these.

  • 3

    Distinctive

    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:

    Check that it's installed with command -v treehouse && treehouse --version.

    line 10
  2. Very specific:

    run git -C "$WT" switch -c <branch> before the first commit.

    line 27
  3. Distinctive:

    Run from inside the user's repository:

    line 33
  4. Distinctive:

    Wrap up: Commit to the branch and push or open a PR if the user wants that.

    line 47
  5. Distinctive:

    If the user wants to keep working in the worktree themselves, don't return it.

    line 56
  6. Very specific:

    Never return or destroy a slot whose lease you don't hold (check lease_holder and lease_id) without asking.

    line 80

“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “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

treehouse

treehouse keeps a pool of git worktrees per repository (default ~/.treehouse/<repo>-<hash>/<slot>/<repo>). When a worktree is returned, it goes back to the pool with dependencies and build caches intact, so the next acquisition starts warm. Use it to isolate work from the user's main checkout, or to give each parallel agent its own checkout.

Check that it's installed with command -v treehouse && treehouse --version. If it's missing, show the user the install command (curl -fsSL https://kunchenguid.github.io/treehouse/install.sh | sh, or go install github.com/kunchenguid/treehouse/v3@latest) and let them run it. Don't pipe it to a shell yourself.

Rule 1: never open a subshell

treehouse, treehouse get (without --lease) and treehouse enter <name> (without --print-path) start an interactive subshell, which hangs a non-interactive Bash tool. Use these forms instead:

GoalCommand
Acquire a worktreetreehouse get --lease --lease-holder <label> --json
Get the path of an existing slottreehouse enter --print-path <name>
Releasetreehouse return --if-lease-id <id> <path>

Rule 2: commit on a branch, never on a detached HEAD

By default a worktree is handed over on a detached HEAD. treehouse return resets the slot, and commits made on a detached HEAD are silently dropped: the return exits 0, and no branch contains them anymore. Always do one of these:

  • acquire with -b <branch> (preferred), or
  • run git -C "$WT" switch -c <branch> before the first commit.

Branches survive a return because they live in the shared repository. Return detaches the slot but never deletes the branch.

Standard workflow

Run from inside the user's repository:

treehouse get --lease --lease-holder "claude-<short-task>" -b "<branch>" --json
# stdout: {"path":"...","lease_id":"...","lease_holder":"...","leased_at":"...","base_branch":"main"}
# banners and post_create hook output go to stderr
  1. Acquire. Save path and lease_id from the JSON output. Useful options:
    • --base <branch>: cut from a branch other than the default. Pass a branch name only, not origin/x, a tag or a SHA. An unknown base is an error, not a fallback.
    • --no-fetch: skip git fetch origin (offline work, or the refs were fetched already).
    • --include-file <manifest>: seed gitignored files (for example .env*) with this manifest instead of the committed .worktreeinclude.
    • --unique-leaf: name the directory <repo>-<slot>, for tooling that keys on the folder name (Compose project, test DB name).
  2. Work in $path. Prefer absolute paths with Read/Edit/Write and git -C "$path" .... For builds and tests, use cd "$path" && <cmd>. A reused slot may already contain node_modules and build output from earlier work, which is intentional. Run the project's install step anyway if the lockfile changed.
  3. Wrap up. Commit to the branch and push or open a PR if the user wants that. Then check the slot:
    • git -C "$path" status --porcelain should be empty.
    • git -C "$path" branch --show-current should name your branch, not print nothing.
  4. Stop any dev servers or watchers you started there. return kills lingering processes in the worktree.
  5. Return. treehouse return --if-lease-id "$lease_id" "$path"
    • exit 0: returned and the lease is released.
    • exit 3: the slot has uncommitted changes, so treehouse refused and left the slot and lease alone. Don't retry in a loop. Commit or stash the work, or ask the user before passing --force. --force discards those changes.
    • exit 1: failure (lease mismatch, process termination, reset). Read the error, then retry or report it.

If the user wants to keep working in the worktree themselves, don't return it. Give them the path and lease id, and tell them how to release it later.

Parallel agents

Give each agent its own lease, with distinct --lease-holder labels and -b branches. Either acquire the leases yourself and pass each subagent its absolute path (telling it to work only there and not to return the slot), or have each subagent follow the standard workflow itself. The pool grows on demand up to max_trees (default 16). get never hands out a leased, in-use or dirty slot.

Inspecting the pool

treehouse status          # human-readable: slot name, state, path, branch, holder
treehouse status --json   # name, path, status, branch, detached, lease_id, lease_holder, processes, ...

Statuses include available, leased, in-use, dirty, unverified, damaged, and you're here. Slot names (1, 2, ...) are stable IDs and are accepted by return, lease and enter from inside the repo. Paths work from anywhere.

Destructive operations: dry-run first, confirm with the user

These delete work or worktrees. Show the user the dry-run output and get explicit approval before adding --yes or --force:

  • treehouse prune (current pool) or treehouse prune --all (every pool under the global root). These are dry runs. Add --yes to delete. Prune only removes clean, idle, unleased slots whose HEAD has landed.
  • treehouse destroy <path>, or treehouse destroy <pool> --all. Also dry runs. Add --yes to execute. Each riskier class needs its own opt-in: --include-unlanded (data loss), --include-in-use (kills processes), --include-leased (exact path only).
  • treehouse return --force: discards uncommitted changes.
  • treehouse return --all: resets every held slot in the pool, including other agents' leases. Don't use it unless the user asks.

Never return or destroy a slot whose lease you don't hold (check lease_holder and lease_id) without asking.

More

See reference.md for configuration (treehouse.toml, user config, .worktreeinclude, hooks, root and in-project pools, worktree path templates, base branch, APFS sharing, jj) and recovery or quarantine handling.

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.