herd

A git worktree manager with pluggable terminal surfaces. herd owns the worktree lifecycle (create / list / review / clean) via git, and delegates "open a tab, split a pane, launch an agent" to a swappable terminal adapter — herdr today, tmux and others later.

The git repo you're standing in is the project — there's no registry to set up. cd into a repo, then reach everything with zero memorization: run herd with no arguments for the full interactive menu, or use a subcommand and let it prompt for anything you leave out.

$ herd
herd — my-repo
? What now?
❯ New feature
  List worktrees
  Review diff
  Open a worktree
  Clean up a worktree
  ──────────────
  Quit

Install

npm install        # install deps
npm run build      # compile to dist/
npm link           # put `herd` on your PATH (dev)
#   …or: npm install -g .

Requires Node ≥ 20, git, and the chosen terminal adapter (herdr) installed.

Concepts

• Current repo = project — no registry. Every command works on the git repo you're in (or any of its worktrees); the repo root, name, and base branch are read from git. ~/.config/herd/config.json holds only global settings (adapter, default agent, split ratio).
• Worktrees — git is the source of truth (git worktree); herd never duplicates that state. New feature worktrees are created as siblings of the repo. A small cache in ~/.config/herd/state.json remembers which terminal session belongs to which worktree, and is always reconciled against the live backend.
• Terminal adapter — a capability-negotiated interface (src/adapters/types.ts). v1 ships the herdr adapter; the core never references a concrete backend.

Commands

All commands act on the current repo — there's no project argument.

| Command | Description | |---|---| | herd / herd menu | Full interactive menu (the SSH-facing surface). | | herd feature [branch] | Create worktree + agent + shell. --desc, --base, --agent, --dir, --ratio, --no-shell, --no-focus, --reuse-branch, --no-fetch. | | herd ls | List worktrees + live agent status. --json. | | herd review [branch] | Walk a worktree's diff vs base file-by-file, comment per file, and hand the feedback to the agent running there. | | herd open [branch] | Open in Cursor (--cursor) and/or focus the terminal session (--terminal). | | herd clean [branches...] | Delete one or more worktrees and close their tabs. --force. |

All positional arguments are optional — omit them to get a picker/input.

Layout when creating a feature

+-----------------------------+
|         agent (claude)      |   ~70%
+-----------------------------+
|   $ quick-commands shell    |   ~30%
+-----------------------------+

The agent command defaults to claude (set defaultAgent in config.json, or override per feature with herd feature --agent …). The optional description is used as the herdr tab label (so you can tell worktrees apart) — it is not sent to the agent as a prompt; the agent opens fresh.

Later (designed for, not built)

• More adapters: tmux, plain/Cursor-only, GUI.
• SSH transport: Tailscale + macOS Remote Login + an authorized_keys forced command pinned to herd menu.
• iPhone push notifications (ntfy) via Claude Code Stop / Notification hooks.