twig 🌳

A Git worktree CLI that gets out of your way — and out of your agent's way too.

Create, jump, and clean up worktrees in one command each. Every command speaks JSON. A real shell hook actually cds. Built with Typer, Rich, Pydantic, and a Rust hot path (twig_core) for validate / glob / porcelain parse under agent swarms.

Install

pipx install twig-cli          # recommended — isolated, puts `twig` on PATH
# or
pip install twig-cli
# or
brew tap ml-lubich/twig https://github.com/ml-lubich/twig && brew install twig
# or from source
git clone https://github.com/ml-lubich/twig && cd twig && pip install -e .

Package name on PyPI is twig-cli; the command you run is still twig. Not on PyPI/Homebrew yet? Install from source — same CLI either way.

Requires Python 3.11+ and git on PATH.

30 seconds

cd your-repo
twig init                        # write .twig.json
eval "$(twig hook zsh)"          # add to ~/.zshrc for real cd

twig new feat-auth               # branch + worktree, source = current branch
twig ls                          # rich table of every worktree
twig go feat-auth                # cd, for real, in your current shell
twig status                      # ahead/behind + dirty, at a glance
twig rm feat-auth                # clean up

Why twig over Branchlet

Branchlet is a solid Ink/React TUI for worktrees. Twig is a CLI-first tool instead — built to be typed, scripted, and driven by agents, not just clicked through.

Bottom line: Branchlet is a worktree menu. Twig is a worktree tool — scriptable, agent-ready, and covered by a test catalog most CLIs don't bother with.

Built for agents

Every twig command that produces output supports --json. Human-formatted tables and colors go to the terminal; the same data is always available as structured JSON for scripts, CI, and LLM agents.

twig agent guide             # markdown playbook for LLM/automation callers
twig agent schema            # JSON Schema for every result type + TwigConfig

twig new feat-x --json | jq -r .path
twig batch-new agent-a agent-b agent-c --json    # one lock, many worktrees
twig ls --json
twig status --json
twig doctor --json                              # exits 1 on real problems
twig exec feat-x --json -- npm test              # one worktree
twig foreach -J 8 --json -- npm test             # parallel across worktrees

Swarm-safe by default: mutating commands take a repo flock so parallel agents don't race git worktree add. Pure-Python fallbacks always work; with a Rust toolchain, pip install builds twig_core for faster validate/glob/porcelain.

Conventions an agent (or script) can rely on:

• Paths and --json payloads → stdout. Human hints and progress → stderr.
• twig go prints TWIG_CD <path> (or {"path": ...} with --json) — the shell hook turns that into a real cd; scripts can parse it directly.
• Non-zero exit code on any failure, with twig: <message> on stderr.
• twig exec/foreach flags (--json, --capture, --all, --continue, -J) go before the literal --; everything after it is passed to the wrapped command verbatim.

Commands

Aliases: create/add → new, list → ls, delete/remove → rm, cd/jump → go, path → which. Add --json/-j to any of the above for machine-readable output. Run twig --install-completion for shell completions.

Configuration

Twig loads config in order (later wins): built-in defaults → ~/.twig/config.json → .twig.json in the repo root. Every field is validated by a Pydantic model — invalid config fails loudly, not silently.

{
  "$schema": "./schema.json",
  "copyPatterns": [".env*", ".vscode/**", ".cursor/**"],
  "copyIgnores": ["**/node_modules/**", "**/dist/**", "**/.git/**"],
  "pathTemplate": "../$BASE_PATH.trees",
  "postCreate": ["uv sync"],
  "editor": "cursor .",
  "deleteBranch": true
}

Template vars available in pathTemplate/postCreate/editor: $BASE_PATH, $WORKTREE_PATH, $BRANCH_NAME, $SOURCE_BRANCH, $NAME. Branchlet's .branchlet.json field names are accepted as aliases, so migrating is a rename.

Run twig init to write the default file, twig config to see what's actually in effect, and twig agent schema for the full JSON Schema.

Shell hook

twig go alone can't change your shell's working directory — no subprocess can. The hook wraps twig in a shell function that intercepts its TWIG_CD marker and runs a real cd. Install it once:

echo 'eval "$(twig hook zsh)"' >> ~/.zshrc && source ~/.zshrc
# bash: twig hook bash   ·   fish: twig hook fish

Everything else — ls, status, new, JSON output — passes straight through untouched.

Development

git clone https://github.com/ml-lubich/twig && cd twig
pip install -e ".[dev]"
pytest                    # 547-case edge catalog + unit/integration/CLI suites
ruff check src tests

Docs live in docs/: OVERVIEW.md, ARCHITECTURE.md, DESIGN.md, API.md, TESTING.md, REQUIREMENTS.md, DEPLOYMENT.md.

License

MIT — see LICENSE.