treebox 0.4.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. --checkout 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. By default it reuses the harness the worktree was created with; an explicit --harness overrides it for that session only, without changing what's recorded on disk. 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 — refreshed on every entry so a host logout or a fresh login reaches the sandbox next time, 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.

Customizing isolation

docker isolation is defined by an operator-owned template — a Dockerfile + container.json you copy out and edit, kept beside the worktree so a boxed agent can't touch its own cage. The shipped image bundles Node 22, uv, gh, ripgrep, and the agent CLIs, so a Node project often needs no image change. For a genuinely separate, non-Python box, copy the template and edit two things — global tooling in the Dockerfile, and postCreate to install your repo's deps (in docker, setup runs postCreate, not the host-mode ecosystem auto-detect):

cp -R "$(python -c 'import treebox.assets, pathlib; print(pathlib.Path(treebox.assets.__file__).parent)')/container" \
      ~/.config/treebox/templates/node

# ~/.config/treebox/templates/node/Dockerfile — Node 22 is already baked in
USER root
RUN npm install -g pnpm@9 typescript tsx
USER ${USERNAME}

// ~/.config/treebox/templates/node/container.json
"postCreate": "if [ -f pnpm-lock.yaml ]; then pnpm install --frozen-lockfile; elif [ -f package-lock.json ]; then npm ci; else npm install; fi"

Then select it per run (--isolation docker --template node) or set template = "node" in your config — a node box and a python box coexist, one per stack. Full walkthrough 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 pre-commit install # lint/format/type hooks (see CONTRIBUTING.md)
uv run --extra dev python -m pytest   # unit + integration suite
./scripts/validate.sh                 # lint + format + 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