treepad

tp

A CLI for managing git worktrees — providing a standardised, extensible set of utilities for working with worktrees.

Overview

tp makes it easy to create, navigate, and manage git worktrees from the command line. The aim is to build a consistent, composable toolset around worktree workflows that can be extended as new patterns emerge.

A primary motivation is parallelising Claude Code instances: each worktree gets its own isolated working directory, allowing multiple AI coding sessions to run simultaneously on different tasks without interfering with each other. tp provides the primitives to spin up, coordinate, and share context between those worktrees.

Built with

• urfave/cli v3 — composable, extensible CLI framework for Go
  • Details for v3 can be found at https://cli.urfave.org/v3/getting-started/

Installation

Homebrew (recommended)

brew install O-Marsters-1997/tap/treepad

go install

go install github.com/O-Marsters-1997/treepad/cmd/tp@latest

This installs the tp binary.

From source

git clone https://github.com/O-Marsters-1997/treepad
cd treepad
just build

This produces a tp binary in the project root. Move it somewhere on your $PATH.

After installing

Initialise a config file in your repo (optional — tp works with zero config):

tp config init

Run tp config show to confirm which config is active.

Agent skill (without installing tp)

If you already have tp, tp skill install sets up the skill for whichever agent harness you use — see below. Without tp, Claude Code users can install it as a plugin instead, since the repo also doubles as a Claude Code plugin marketplace:

/plugin marketplace add O-Marsters-1997/treepad
/plugin install treepad@treepad

Configuration

tp works with zero configuration. See docs/configuration.md for more info on how to configure it and what the defaults are.

Usage

tp [--verbose | -v] [--profile] <command> [options]

Use --profile to print a per-stage timing breakdown to stderr after the command completes:

tp --profile new feature-x
# => profile: new feature-x (total 0.842s)
#      stage              duration    pct
#    ─────────────────────────────────────
#      git.worktree_add   0.501s    59.5%  ◀
#      sync               0.201s    23.9%
#      artifact.write     0.140s    16.6%
#    ─────────────────────────────────────
#      total              0.842s   100.0%

Main commands

sync — Sync configs and generate artifact files across all git worktrees:

# Sync configs and generate artifact files from the main worktree
tp sync

# Sync only — skip artifact file generation
tp sync --sync-only

# Use the current directory as the config source instead of the main worktree
tp sync --use-current

# Include extra file patterns in the sync
tp sync --include ".prettierrc" --include ".eslintrc.json"

# Debug what tp is doing
tp --verbose sync

new — Create a new git worktree with configs synced and artifact file generated:

# Create a new worktree for branch 'feature-x' branched from main (cd's into it automatically)
tp new feature-x

# Create a worktree from a different base ref
tp new bugfix-y --base develop

# Create a worktree and open the artifact file
tp new feature-z --open

# Stay in the current directory instead of cd-ing into the new worktree
tp new feature-z -c

Shell integration: tp new prints a cd directive that is acted on by a shell wrapper function. Add the following to your ~/.zshrc or ~/.bashrc:

eval "$(tp shell-init)"

new --ticket — Create a worktree from a ticket and hand off to an agent:

# Create a worktree from a ticket, using a bare ref against the configured ticket_url
tp new feature-x --ticket ENG-42

# A full ticket URL works with no config, and overrides ticket_url when set
tp new feature-x --ticket https://github.com/acme/api/issues/42

# Create a worktree from a different base ref
tp new bugfix-z --ticket ENG-10 --base develop

tp does not read your tracker and writes no prompt — it hands the ticket URL to [from_spec] agent_command and the agent fetches the body itself. Set [from_spec] ticket_url in .treepad.toml to use bare refs. See docs/from-spec.md.

playbook new — Write a playbook saying which skills a recurring shape of work should use:

tp playbook new task-dashboard < playbook.md

The body is written verbatim to .claude/playbooks/task-dashboard.md in the main worktree and propagated by [sync]. Name it on the ticket (Playbook: task-dashboard) and the agent picks it up when it reads the ticket. See ADR 0002.

batch sync — Reconcile a Batch of Tickets into a fleet of stacked worktrees:

# Preview what a Batch would do
tp batch sync --dry-run

# Reconcile every Batch, spawning agents for newly-ready members
tp batch sync --launch

# List every Batch, its Chains, and each member's ticket/ref/branch/base
tp batch list

A Batch is a collection of Tickets declared by a Manifest — an uncommitted TOML file under <git-common-dir>/treepad/batches/*.toml naming one or more Chains (ordered runs of Tickets, each worktree branched from the one before it). Treepad reads Manifests; it never writes one — that's an external dependency: to-tickets must learn to emit them.

name = "silent-refresh"
[[chain]]
tickets = ["ENG-12", "ENG-13"]
[[chain]]
tickets = ["ENG-14"]

tp batch sync materialises each Chain's worktrees in order and links ready pull requests into a GitHub Stack with gh stack link — requires gh installed and authenticated; without it, only each Chain's first member materialises and the rest report gh-required. Configure [batch] launch to start an agent automatically once a member is ready (see docs/configuration.md); --launch spawns it via the Launcher, which writes to that worktree's Activity file.

Chain depth is a review-latency multiplier. Layer five cannot land until four reviews complete below it, and every merge below rewrites the base under the agents above. Deep Chains optimise writing throughput and pessimise review throughput, which is the opposite of the point. Shallow and wide beats deep and narrow.

gh stack link is additive only — treepad can build a Chain into a Stack but can never take one apart. A Manifest edited after its Chain is linked leaves a Stack on GitHub that no treepad command can correct; fix it by hand on github.com.

See docs/commands.md for the full reference.

remove — Remove a git worktree and its associated files:

# Remove a completed feature branch (switch out of it first)
cd ../main-repo
tp remove feature-x

# Discard uncommitted changes and delete an unmerged branch
tp remove --force feature-x

prune — Remove all worktrees whose branches are merged into a base branch, or force-remove all non-main worktrees:

# Remove all worktrees whose branches are merged into main
tp prune

# Preview without executing
tp prune --dry-run

# Check merges against a different base branch
tp prune --base develop

# Force-remove all non-main worktrees (with confirmation)
tp prune --all

cd — cd into an existing worktree by branch name, or toggle back to the previous one:

# cd into an existing worktree (shell integration handles the directory change)
tp cd feature-x

# toggle back to the previous worktree (like cd -)
tp cd -

Requires eval "$(tp shell-init)" in your shell rc — the same wrapper used by new.

base — return to the main worktree from any branch worktree:

# cd back to the main worktree
tp base

Requires eval "$(tp shell-init)" in your shell rc.

status — List all worktrees with their branch, dirty state, ahead/behind count, and last commit:

# Show status of all worktrees in a table
tp status

# Emit JSON for scripting or dashboards
tp status --json

ui — Open a live interactive fleet view (requires a TTY):

# Open the BubbleTea TUI fleet monitor
tp ui

Requires eval "$(tp shell-init)" for the Enter→cd action to work.

exec — Run a command in a specific worktree with full stdio passthrough:

# Run a script (detected task runner handles it automatically)
tp exec feature-x build

# Run a raw command in the worktree root
tp exec feature-x cargo test

# List available scripts and detected runner for a worktree
tp exec feature-x

The exec command auto-detects the project task runner (just, npm/pnpm/yarn/bun, make, poetry/uv) by checking for marker files. If the command matches an enumerated script, it routes through the runner (e.g. just build, pnpm run build). Otherwise, it executes the command directly in the worktree root. Override auto-detection via [exec] runner = "just" in .treepad.toml.

diff — Show the diff of a worktree against a base branch:

# Show diff vs main branch (colored, paged via git config)
tp diff feature-x

# Diff against a different base branch
tp diff feature-x --base develop

# Write a plain patch to a file (no color)
tp diff feature-x -o ~/my-feature.patch

# Show only changed files and line counts
tp diff feature-x -- --stat

# Limit diff to a specific subdirectory
tp diff feature-x -- -- src/

The diff command uses git diff <base>...HEAD three-dot semantics (matches GitHub PR diff view) and respects your git configuration (pager, delta, diff-so-fancy). Inherits color and pager config from the target worktree's git setup. Pass --output / -o to write an uncolored patch to a file.

doctor — Report cross-worktree health issues (stale, merged, remote-gone, artifact-missing, config-drift):

# Show a table of findings
tp doctor

# Flag worktrees with no commit in the last 14 days
tp doctor --stale-days 14

# Check merges against a different base
tp doctor --base develop

# Skip remote branch checks (faster, works offline)
tp doctor --offline

# Emit JSON for scripting
tp doctor --json

# Exit non-zero if any findings are reported (useful in CI)
tp doctor --strict

config — Manage tp configuration:

# Write a default .treepad.toml to the main worktree root
tp config init

# Write config to the global config path
tp config init --global

# Show the resolved config and which source(s) contributed
tp config show

skill — Manage treepad's agent skills:

# Install every skill to ~/.agents/skills (and link ~/.claude/skills if present)
tp skill install

# Install into the repo instead, so it's committed and shared
tp skill install --local

See docs/commands.md for the full command reference.

All commands

tp [--verbose] <command>
├── sync [options] [source-path]
├── new [options] <branch>
├── batch
│   ├── list [--json]
│   └── sync [options]
├── remove <branch>
├── prune [options]
├── cd <branch | ->
├── base
├── status [--json]
├── ui
├── exec <branch> [command] [args...]
├── diff [options] <branch> [-- <git-diff-args>...]
├── doctor [options]
├── shell-init
├── config
│   ├── init [--global]
│   └── show
├── skill
│   ├── install [name...] [--local] [--force]
│   └── list
└── playbook
    └── new <name> [--force]

Testing

tp has two test layers:

• Unit/integration — mocked git runner, runs with just test (go test ./...). Fast inner-loop feedback.
• End-to-end — builds tp in-process, drives it against a real throwaway git repo per scenario, asserts on stdout, exit codes, and filesystem state. Runs with just test-e2e (go test -tags=e2e ./cmd/tp/...).

Adding an e2e test

1. Create cmd/tp/testdata/script/<name>.txtar.
2. Start the script with tp-init-repo (creates a clean git repo and cds into it).
3. Call exec tp <command> [args...] to run the binary.
4. Assert with stdout <pattern>, exists <path>, ! exists <path>, or grep <pattern> <file>.

See the testscript docs for the full command reference.

Development