treebox 0.3.0

Isolated, ready-to-run git worktrees for AI coding agents — host-native or docker-sandboxed.

treebox

Isolated, ready-to-run git worktrees for AI coding agents.

Documentation · Install · Usage · How it works · Seth Peters

---

Run treebox create and it fetches, cuts a worktree from a fresh origin/<base>, copies your .env, installs dependencies from a shared cache, and launches claude or codex inside. No branch name needed up front: the worktree gets a stable name (yours, or a generated petname) and an un-pushable treebox/<name> placeholder branch the agent renames when the work takes shape. Agents work the same repo in parallel without collisions — on a laptop or over plain SSH.

Built by Seth Peters as a small, operator-focused layer for AI agent infrastructure: git worktrees, sandbox boundaries, subscription auth, and repeatable developer environments. If that is the kind of problem you are solving, the docs go deeper on the design tradeoffs — and I'm on LinkedIn if you want to compare notes.

Provisioning is identical everywhere; a pluggable isolation mode decides where the agent runs:

--isolation	Sandbox	Agent runs in
host (default)	none	the worktree shell
docker	sandboxed	a docker container, with your .env + caches mounted

Every agent ships its own cage

Every coding agent invents its own answer to "run me in parallel" and "don't let me touch the wrong thing" — a different config file, a different schema, a different word for the same idea:

Agent	Sandbox / permission config	Built-in worktrees	Config lives in
Claude Code	permissions allow/ask/deny + native OS sandbox (Seatbelt/bubblewrap) + dev container	Yes (--worktree)	.claude/settings.json, .devcontainer/
OpenAI Codex	sandbox_mode × approval_policy (Seatbelt / Landlock+seccomp)	No in CLI (app only)	~/.codex/config.toml, [profiles.*]
opencode	permission per-tool allow/ask/deny (no OS sandbox)	No (community plugins)	opencode.json
pi	none built-in ("all permissions by default"); BYO Docker/VM + trust prompt	No in core (pi-subagents)	~/.pi/agent/settings.json

Learn one and it teaches you nothing about the next, and none of it ports across tools. treebox owns the isolation layer instead — one worktree-per-branch layout, one operator-owned sandbox, one config file — and launches your agent of choice inside it. Learn treebox once; swap the agent, keep the box. Full comparison with citations: Agents & sandboxing.

Install

curl -fsSL https://raw.githubusercontent.com/Seth-Peters/treebox/main/install.sh | sh

The script installs with uv and stops with instructions if uv is missing — it never installs a package manager behind your back. Or install directly:

uv tool install git+https://github.com/Seth-Peters/treebox

Host isolation needs only git and a logged-in agent CLI (claude / codex); docker isolation additionally needs just docker — no Node.js, no extra CLIs. See the install guide for requirements and installer overrides.

Usage

The whole surface is five commands, and a worktree's life runs through all of them.

Check the host. doctor verifies exactly what create will need — git, agent logins, .env, credentials for the required fetch — and prints the fix for anything missing:

treebox doctor

Create. Fetches origin, cuts a worktree from the fresh origin/main, copies .env and submodules, syncs dependencies from the shared cache, and launches the agent:

treebox create                          # generated name (brave-otter), host-native
treebox create fix-auth                 # named up front
treebox create fix-auth --isolation docker   # sandboxed
treebox create --checkout feature/auth       # exact existing branch (resume, PR review)
treebox create auth-fixes --base feature/auth   # stack on any base branch

The optional name is one slug token and is the worktree's permanent identity; the branch starts as a treebox/<name> placeholder that a per-worktree pre-push guard keeps un-pushable — rename it conventionally (git branch -m feature/user-auth, fix/login-race, chore/bump-deps, …) when the work has a shape, then push. So a machine-generated name can never become a PR title. -b is the one path that skips the placeholder: it checks out an existing branch exactly.

--base takes any branch, not just main — branch off dev, or stack a new worktree on top of an existing PR's branch, even while that branch is checked out in another worktree. It resolves as the freshly fetched origin/<base>, so push the base first if its latest commits only exist locally.

Enter. Come back to an existing worktree, picking the agent per entry. The ref is the name, the current branch (renames are followed live), or a unique substring of either. Dependencies re-sync only if the lockfile changed since last time:

treebox enter fix-auth --harness claude
treebox enter fix-auth --harness codex -- --resume   # args after -- go to the agent

List. See what exists, what each worktree was last doing, and what has gone stale — sorted by recency, with treebox/* placeholders flagged ⚠ unnamed:

treebox list

Tear down. Remove one or more worktrees — and, when you're done, their branches. Refuses to delete uncommitted work unless forced. Run it with no refs and treebox walks you through an arrow-key picker, each worktree annotated with a "will I lose work?" badge (dirty/ahead/merged, plus PR state when gh/glab is present):

treebox teardown fix-auth brave-otter --delete-branch
treebox teardown                        # pick interactively

treebox is built to be scripted, including by agents: every command takes --json (data to stdout, diagnostics to stderr, a schema that only gains fields within a version), --dry-run prints the exact commands without running them, and exit codes are stable (0 ok · 2 usage · 3 not found · 4 auth · 5 conflict). Full reference in the usage guide.

Design

• Never silently stale. create requires a successful git fetch origin and branches from the fresh origin/<base>; a failed fetch exits 4 loudly. --no-fetch is the only (explicit) escape.
• Warmth lives in the cache, not the tree. Installs hardlink from shared caches (~/.cache/uv, the pnpm store, …) reused across worktrees and containers.
• The sandbox config lives outside the box. The container is rendered from your operator-owned template beside the worktree, never mounted — a boxed agent can't edit its own cage, and the target repo's container config and hooks are ignored.
• Credentials go in as scoped copies. Only the agents' login files are copied into a throwaway per-worktree dir — never the live ~/.claude / ~/.codex — and treebox uses your subscription login, never ANTHROPIC_API_KEY.

More in how it works.

Configuration

Optional, and user-level only (~/.config/treebox/config.toml) — treebox never reads config from the target repo:

isolation = "docker"  # host | docker
harness = "claude"  # claude | codex
base   = "main"

All keys, shared-cache overrides, setup hooks, and sandbox templates are covered in the configuration guide.

Development

git clone https://github.com/Seth-Peters/treebox && cd treebox
uv run treebox ...                    # run the CLI from the working tree
uv run --extra dev python -m pytest   # unit + integration suite
./scripts/validate.sh                 # lint + tests + live host-runner smoke

Contributing

Small fixes and docs improvements are welcome. See CONTRIBUTING.md. The roadmap is intentionally light for now: ROADMAP.md.

License

PolyForm Noncommercial 1.0.0