treebox 0.3.0__tar.gz → 0.4.0__tar.gz

treebox-0.4.0/.github/workflows/autofix.yml

@@ -0,0 +1,69 @@
+name: Autofix
+
+# Applies ruff's auto-fixes (`ruff check --fix` + `ruff format`) to pull requests
+# and commits the result back to the PR branch. This is the CI counterpart to the
+# pre-commit hooks: if a change lands unformatted (hooks skipped), the branch is
+# fixed in place instead of just failing the CI gate. Skips fork PRs, where the
+# workflow token cannot push, and its own commits, to avoid loops.
+#
+# Gotcha: pushes made with the default GITHUB_TOKEN (from actions/checkout) do
+# NOT trigger new workflow runs. So the auto-fixed commit this job pushes will
+# not re-run ci.yml. Two implications:
+#   - If branch protection REQUIRES the CI status checks, the auto-fixed SHA will
+#     have no reported checks and the PR will stall. The remedy is to check out
+#     and push using a PAT or GitHub App token stored as a repo secret (e.g.
+#     AUTOFIX_TOKEN) instead of GITHUB_TOKEN, so the push re-triggers CI.
+#   - To close the "merged with a commit CI never validated" hole regardless,
+#     this job re-runs the ruff + mypy checks on the fixed tree below and fails
+#     rather than pushing if they don't pass, so the exact pushed commit is
+#     validated within this run.
+
+on:
+  pull_request:
+
+concurrency:
+  group: autofix-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+
+jobs:
+  autofix:
+    name: ruff --fix
+    runs-on: ubuntu-latest
+    if: >-
+      github.event.pull_request.head.repo.full_name == github.repository &&
+      github.actor != 'github-actions[bot]'
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ github.head_ref }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          enable-cache: true
+
+      - name: ruff check --fix
+        run: uv run --extra dev ruff check --fix src tests
+
+      - name: ruff format
+        run: uv run --extra dev ruff format src tests
+
+      - name: Validate fixed tree
+        run: |
+          uv run --extra dev ruff check src tests
+          uv run --extra dev ruff format --check src tests
+          uv run --extra dev mypy
+
+      - name: Commit fixes
+        run: |
+          if git diff --quiet; then
+            echo "No formatting or lint fixes needed."
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git commit -am "style: apply ruff --fix and format"
+          git push

{treebox-0.3.0 → treebox-0.4.0}/.github/workflows/ci.yml

@@ -29,6 +29,9 @@ jobs:
       - name: Lint
         run: uv run -p ${{ matrix.python-version }} --extra dev ruff check src tests
 
+      - name: Format
+        run: uv run -p ${{ matrix.python-version }} --extra dev ruff format --check src tests
+
       - name: Type check
         run: uv run -p ${{ matrix.python-version }} --extra dev mypy
 

treebox-0.4.0/.pre-commit-config.yaml

@@ -0,0 +1,25 @@
+# Pre-commit hooks: keep every commit lint-clean, formatted, and type-checked.
+# Install once with `uv run --extra dev pre-commit install` (or `pre-commit install`).
+# Run against everything with `uv run --extra dev pre-commit run --all-files`.
+#
+# Keep the ruff rev in sync with the `ruff>=…` pin in pyproject.toml's [dev] extra.
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.20
+    hooks:
+      # Lint and auto-fix (import sorting, pyupgrade, simplify, …), then format.
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+
+  # mypy runs from the project's own dev environment so it sees typer/questionary
+  # stubs and the [tool.mypy] config (files = ["src"]). pass_filenames is off
+  # because that config already selects the files to check.
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy
+        entry: uv run --extra dev mypy
+        language: system
+        types: [python]
+        pass_filenames: false

{treebox-0.3.0 → treebox-0.4.0}/CLAUDE.md

@@ -19,9 +19,11 @@ template it provisions is separately pinned to CPython 3.14.6).
 uv run treebox ...                      # run the CLI from the working tree
 uv run --extra dev python -m pytest     # full unit + integration suite
 uv run --extra dev python -m pytest tests/test_units.py::test_name   # single test (or -k <pattern>)
-ruff check src tests                    # lint
+uv run --extra dev ruff check src tests # lint
+uv run --extra dev ruff format --check src tests   # format check (drop --check to apply)
 uv run --extra dev mypy                 # type check (config in pyproject.toml)
-./scripts/validate.sh                   # lint + tests + live host-runner smoke (real uv, throwaway local remote)
+uv run --extra dev pre-commit install   # install lint/format/type hooks (see CONTRIBUTING.md)
+./scripts/validate.sh                   # lint + format + tests + live host-runner smoke (real uv, throwaway local remote)
 uv pip install -e ".[dev]"              # editable dev environment
 uv run --extra docs mkdocs serve        # docs site (docs/ + mkdocs.yml), live-reloading
 uv run --extra docs mkdocs build --strict   # build docs to site/ (gitignored)

treebox-0.4.0/CONTRIBUTING.md

@@ -0,0 +1,52 @@
+# Contributing
+
+treebox is a small, one-maintainer project. Contributions are welcome, but the scope is intentionally modest.
+
+## Good contributions
+
+- Bug fixes with a clear reproduction.
+- Documentation fixes that make install, usage, or runner behavior clearer.
+- Small compatibility fixes that preserve the existing CLI and scripting behavior.
+
+For larger feature ideas, open an issue first so we can decide whether they fit the project.
+
+## Local checks
+
+Install the pre-commit hooks once so every commit is auto-formatted, lint-fixed,
+and type-checked (`ruff format`, `ruff check --fix`, and `mypy`):
+
+```bash
+uv run --extra dev pre-commit install
+```
+
+Note: `pre-commit install` has no effect inside a treebox worktree, because
+treebox sets `core.hooksPath` for its own pre-push guard, so git ignores the
+hook pre-commit writes to `.git/hooks`. Run the hooks manually there with
+`uv run --extra dev pre-commit run --all-files`.
+
+If the hooks are skipped, the Autofix CI workflow applies the same `ruff --fix`
+and `ruff format` to same-repo PRs and pushes the result back. Note that pushes
+made with the default `GITHUB_TOKEN` do not re-trigger CI, so if this repo ever
+requires the CI status checks under branch protection, the auto-fixed commit
+will have no reported checks and the PR will stall; the remedy is to push from
+the workflow using a PAT or GitHub App token stored as a repo secret (e.g.
+`AUTOFIX_TOKEN`) instead of `GITHUB_TOKEN`.
+
+For code changes, run the relevant checks before opening a PR:
+
+```bash
+uv run --extra dev python -m pytest
+uv run --extra dev ruff check src tests
+uv run --extra dev ruff format --check src tests
+uv run --extra dev mypy
+```
+
+For docs-only changes, this is enough:
+
+```bash
+uv run --extra docs mkdocs build --strict
+```
+
+## Boundaries
+
+Please preserve the basics: fresh refs by default, no trust in target-repo sandbox config, stable CLI output for scripts, and subscription-based agent auth.

{treebox-0.3.0 → treebox-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: treebox
-Version: 0.3.0
+Version: 0.4.0
 Summary: Isolated, ready-to-run git worktrees for AI coding agents — host-native or docker-sandboxed.
 Project-URL: Homepage, https://github.com/Seth-Peters/treebox
 Project-URL: Documentation, https://seth-peters.github.io/treebox/
@@ -23,9 +23,11 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Version Control :: Git
 Requires-Python: >=3.11
 Requires-Dist: questionary<3,>=2
+Requires-Dist: rich<16,>=13
 Requires-Dist: typer<1.0,>=0.12
 Provides-Extra: dev
 Requires-Dist: mypy>=1.14; extra == 'dev'
+Requires-Dist: pre-commit>=4; extra == 'dev'
 Requires-Dist: pytest-cov>=6; extra == 'dev'
 Requires-Dist: pytest>=8; extra == 'dev'
 Requires-Dist: ruff>=0.15; extra == 'dev'
@@ -149,7 +151,7 @@ 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
+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
@@ -157,10 +159,11 @@ 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:
+**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:
 
 ```bash
 treebox enter fix-auth --harness claude
@@ -207,8 +210,9 @@ conflict). Full reference in the
   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`.
+  `~/.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](https://seth-peters.github.io/treebox/how-it-works/).
 
@@ -227,13 +231,47 @@ All keys, shared-cache overrides, setup hooks, and sandbox templates are
 covered in the
 [configuration guide](https://seth-peters.github.io/treebox/configuration/).
 
+## 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):
+
+```bash
+cp -R "$(python -c 'import treebox.assets, pathlib; print(pathlib.Path(treebox.assets.__file__).parent)')/container" \
+      ~/.config/treebox/templates/node
+```
+
+```dockerfile
+# ~/.config/treebox/templates/node/Dockerfile — Node 22 is already baked in
+USER root
+RUN npm install -g pnpm@9 typescript tsx
+USER ${USERNAME}
+```
+
+```json
+// ~/.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](https://seth-peters.github.io/treebox/configuration/#worked-example-a-node-sandbox-not-python).
+
 ## Development
 
 ```bash
 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 + tests + live host-runner smoke
+./scripts/validate.sh                 # lint + format + tests + live host-runner smoke
 ```
 
 ## Contributing

{treebox-0.3.0 → treebox-0.4.0}/README.md

@@ -114,7 +114,7 @@ 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
+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
@@ -122,10 +122,11 @@ 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:
+**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:
 
 ```bash
 treebox enter fix-auth --harness claude
@@ -172,8 +173,9 @@ conflict). Full reference in the
   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`.
+  `~/.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](https://seth-peters.github.io/treebox/how-it-works/).
 
@@ -192,13 +194,47 @@ All keys, shared-cache overrides, setup hooks, and sandbox templates are
 covered in the
 [configuration guide](https://seth-peters.github.io/treebox/configuration/).
 
+## 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):
+
+```bash
+cp -R "$(python -c 'import treebox.assets, pathlib; print(pathlib.Path(treebox.assets.__file__).parent)')/container" \
+      ~/.config/treebox/templates/node
+```
+
+```dockerfile
+# ~/.config/treebox/templates/node/Dockerfile — Node 22 is already baked in
+USER root
+RUN npm install -g pnpm@9 typescript tsx
+USER ${USERNAME}
+```
+
+```json
+// ~/.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](https://seth-peters.github.io/treebox/configuration/#worked-example-a-node-sandbox-not-python).
+
 ## Development
 
 ```bash
 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 + tests + live host-runner smoke
+./scripts/validate.sh                 # lint + format + tests + live host-runner smoke
 ```
 
 ## Contributing

{treebox-0.3.0 → treebox-0.4.0}/docs/configuration.md

@@ -40,7 +40,7 @@ command-line flag  >  config.toml  >  built-in default
 | Key        | Default              | What it controls                                          |
 | ---------- | -------------------- | --------------------------------------------------------- |
 | `isolation`| `host`               | Where agents run: the worktree shell, or a docker sandbox. |
-| `harness`  | `claude`             | Which agent `create`/`enter` launch by default.           |
+| `harness`  | `claude`             | Which agent `create` launches by default; `enter` reuses the harness the worktree was created with unless `--harness` overrides it. |
 | `base`     | `main`               | Base branch for new branches (resolved as `origin/<base>`). |
 | `root`     | `.treebox/worktrees` | Where worktree directories are created, relative to the repo. |
 | `env_file` | `.env`               | The secrets file copied into every new worktree.          |
@@ -66,7 +66,9 @@ cp -R "$(python -c 'import treebox.assets, pathlib; print(pathlib.Path(treebox.a
 syntax, with `${workspaceName}` substituted per worktree), and `runArgs` feed
 `docker run`; `postCreate` is the setup command exec'd in the workspace after
 the container starts. The firewall overlay in `firewall.json` deep-merges on
-top when `--firewall` is set.
+top when the firewall is enabled (`firewall = true` in the config, or
+`--firewall` per run; `--no-firewall` opts a single run out of a config
+default).
 
 Templates in `~/.config/treebox/templates/<name>` are picked by the
 `template` config key or per-invocation with `--template <name>`. The
@@ -75,11 +77,51 @@ mount — so a sandboxed agent can't edit it. Any container config in the
 target repo itself is deliberately ignored; see
 [how it works](how-it-works.md#the-sandbox-config-lives-outside-the-box).
 
+### Worked example: a Node sandbox, not Python
+
+Say your project is Node and you want a box with nothing to do with the
+default Python one. Keep a separate named template and select it per run —
+a `node` box and a `python` box coexist, one per stack. Copy the template out:
+
+```bash
+cp -R "$(python -c 'import treebox.assets, pathlib; print(pathlib.Path(treebox.assets.__file__).parent)')/container" \
+      ~/.config/treebox/templates/node
+```
+
+The shipped image already bundles Node 22 (plus uv, `gh`, ripgrep, and the
+agent CLIs), so a Node project often needs no image change at all. Add any
+**global** tooling to `~/.config/treebox/templates/node/Dockerfile`:
+
+```dockerfile
+USER root
+RUN npm install -g pnpm@9 typescript tsx
+USER ${USERNAME}
+```
+
+Then the one docker-specific step: point `postCreate` in `container.json` at
+your project's install command. In docker isolation, dependency setup is
+driven by the template's `postCreate` — not the host-mode ecosystem
+auto-detect — so a non-Python project must wire its own install here (the
+npm/pnpm cache is mounted, so it stays warm across worktrees):
+
+```json
+"postCreate": "if [ -f pnpm-lock.yaml ]; then pnpm install --frozen-lockfile; elif [ -f package-lock.json ]; then npm ci; else npm install; fi"
+```
+
+Now provision with it, per-invocation or as your default (`template = "node"`):
+
+```bash
+treebox create my-feature --isolation docker --template node
+```
+
+First run builds your image (cached after that), provisions the worktree, runs
+`postCreate` to install deps, and launches the agent inside.
+
 ## Environment variables
 
 | Variable          | Effect                                                        |
 | ----------------- | ------------------------------------------------------------- |
-| `TREEBOX_CONFIG`  | Explicit path to the config file (overrides the XDG lookup).  |
+| `TREEBOX_CONFIG`  | Explicit path to the config file (overrides the XDG lookup). Setting it asserts the file exists — a missing file here is a loud error (exit `2`), not a silent fall-back to defaults. |
 | `XDG_CONFIG_HOME` | Standard XDG base for `treebox/config.toml` and templates.    |
 | `XDG_CACHE_HOME`  | Standard XDG base for the shared package caches treebox mounts. |
 

{treebox-0.3.0 → treebox-0.4.0}/docs/how-it-works.md

@@ -104,5 +104,7 @@ treebox assumes the caller is often another program:
 - **`--json` with a `schemaVersion`** that only gains fields within a version
   (git-porcelain discipline), plus `--print` and `--dry-run` for scripts that
   want the commands, not the side effects.
-- **Per-worktree locking**, so two concurrent `create fix-auth` calls
-  conflict cleanly (`5`) instead of corrupting a worktree.
+- **Per-worktree locking**, held by `create`, `enter`, and `teardown` alike,
+  so racing operations on one name — two `create fix-auth` calls, or a
+  `teardown fix-auth` against a concurrent provision — conflict cleanly (`5`)
+  instead of corrupting or half-removing a worktree.

{treebox-0.3.0 → treebox-0.4.0}/docs/index.md

@@ -28,13 +28,14 @@ sandbox.
 <div class="tx-terminal">
 <div class="tx-terminal__bar"><span class="tx-dot tx-dot--r"></span><span class="tx-dot tx-dot--y"></span><span class="tx-dot tx-dot--g"></span><button class="tx-copy" type="button" data-copy="treebox create --isolation docker" aria-label="Copy command"><svg viewBox="0 0 24 24" width="15" height="15" aria-hidden="true"><path fill="currentColor" d="M19 21H8V7h11m0-2H8a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h11a2 2 0 0 0 2-2V7a2 2 0 0 0-2-2m-3-4H4a2 2 0 0 0-2 2v14h2V3h12z"/></svg><span class="tx-copy__done">✓</span></button></div>
 <div class="tx-screen">
-<div class="t-line" style="--d:0s"><span class="c-ok">$ </span><span class="t-type">treebox create --isolation docker</span></div>
+<div class="t-scene" data-dur="8600">
+<div class="t-line" style="--d:0s;--n:33"><span class="c-ok">$ </span><span class="t-type">treebox create --isolation docker</span></div>
 <div class="t-line" style="--d:1.8s"> </div>
 <div class="t-line" style="--d:1.8s">  <span class="c-acc">●</span> create   <b>brave-otter</b></div>
 <div class="t-line" style="--d:2.0s"> </div>
 <div class="t-line" style="--d:2.0s">    <span class="c-dim">branch</span>     treebox/brave-otter  <span class="c-dim">·  placeholder — rename before push</span></div>
 <div class="t-line" style="--d:2.1s">    <span class="c-dim">base</span>       main</div>
-<div class="t-line" style="--d:2.2s">    <span class="c-dim">isolation</span>     docker  <span class="c-dim">→</span>  claude</div>
+<div class="t-line" style="--d:2.2s">    <span class="c-dim">isolation</span>  docker  <span class="c-dim">→</span>  claude</div>
 <div class="t-line" style="--d:2.4s"> </div>
 <div class="t-line" style="--d:2.4s;--run:.8s">    <span class="t-g"><span class="t-spin"></span><span class="t-check">✓</span></span> fetch      <span class="c-dim">origin up to date</span></div>
 <div class="t-line" style="--d:3.2s;--run:.5s">    <span class="t-g"><span class="t-spin"></span><span class="t-check">✓</span></span> worktree   <span class="c-dim">.treebox/worktrees/brave-otter</span></div>
@@ -45,6 +46,58 @@ sandbox.
 <div class="t-line" style="--d:6.9s"> </div>
 <div class="t-line" style="--d:6.9s">  <span class="c-ok">Ready</span> <span class="c-dim">in 22.6s — launching</span> claude</div>
 </div>
+<div class="t-scene" data-dur="5800">
+<div class="t-line" style="--d:0s;--n:34"><span class="c-ok">$ </span><span class="t-type">treebox enter brave-otter -H codex</span></div>
+<div class="t-line" style="--d:1.7s"> </div>
+<div class="t-line" style="--d:1.7s">  <span class="c-acc">●</span> enter   <b>brave-otter</b>  <span class="c-dim">·  feature/user-auth</span></div>
+<div class="t-line" style="--d:1.9s"> </div>
+<div class="t-line" style="--d:1.9s">    <span class="c-dim">isolation</span>  docker  <span class="c-dim">→</span>  codex</div>
+<div class="t-line" style="--d:2.1s"> </div>
+<div class="t-line" style="--d:2.2s;--run:.3s">    <span class="t-g"><span class="t-spin"></span><span class="t-check">✓</span></span> secrets    <span class="c-dim">copied</span></div>
+<div class="t-line" style="--d:2.7s">    <span class="c-dim">· deps       unchanged · skipping setup</span></div>
+<div class="t-line" style="--d:2.9s"> </div>
+<div class="t-line" style="--d:3.0s">  <span class="c-ok">Ready</span> <span class="c-dim">in 1.4s — launching</span> codex</div>
+<div class="t-line" style="--d:4.4s"> </div>
+<div class="t-line" style="--d:4.5s">^C</div>
+</div>
+<div class="t-scene" data-dur="4800">
+<div class="t-line" style="--d:0s;--n:35"><span class="c-ok">$ </span><span class="t-type">treebox enter brave-otter -H claude</span></div>
+<div class="t-line" style="--d:1.8s"> </div>
+<div class="t-line" style="--d:1.8s">  <span class="c-acc">●</span> enter   <b>brave-otter</b>  <span class="c-dim">·  feature/user-auth</span></div>
+<div class="t-line" style="--d:2.0s"> </div>
+<div class="t-line" style="--d:2.0s">    <span class="c-dim">isolation</span>  docker  <span class="c-dim">→</span>  claude</div>
+<div class="t-line" style="--d:2.2s"> </div>
+<div class="t-line" style="--d:2.3s;--run:.3s">    <span class="t-g"><span class="t-spin"></span><span class="t-check">✓</span></span> secrets    <span class="c-dim">copied</span></div>
+<div class="t-line" style="--d:2.8s">    <span class="c-dim">· deps       unchanged · skipping setup</span></div>
+<div class="t-line" style="--d:3.0s"> </div>
+<div class="t-line" style="--d:3.1s">  <span class="c-ok">Ready</span> <span class="c-dim">in 1.2s — launching</span> claude</div>
+</div>
+<div class="t-scene" data-dur="4800">
+<div class="t-line" style="--d:0s;--n:10"><span class="c-ok">$ </span><span class="t-type">treebox ls</span></div>
+<div class="t-line" style="--d:1.0s"> </div>
+<div class="t-line" style="--d:1.1s">  <span class="c-dim">NAME          BRANCH              LAST COMMIT             AGE   DEPS      ENV</span></div>
+<div class="t-line" style="--d:1.1s">  <span class="c-dim">─────────────────────────────────────────────────────────────────────────────</span></div>
+<div class="t-line" style="--d:1.3s">  brave-otter   feature/user-auth   <span class="c-dim">feat: add signup flow    5m</span>   <span class="c-ok">● fresh</span>   <span class="c-ok">● present</span></div>
+</div>
+<div class="t-scene" data-dur="6600">
+<div class="t-line" style="--d:0s;--n:22"><span class="c-ok">$ </span><span class="t-type">treebox rm brave-otter</span></div>
+<div class="t-line" style="--d:1.4s;--td:2s">Remove worktree brave-otter? [y/N]: <span class="t-in">y</span></div>
+<div class="t-line" style="--d:2.5s"> </div>
+<div class="t-line" style="--d:2.5s">  <span class="c-acc">●</span> teardown   <b>brave-otter</b></div>
+<div class="t-line" style="--d:2.7s"> </div>
+<div class="t-line" style="--d:2.8s;--run:.7s">    <span class="t-g"><span class="t-spin"></span><span class="t-check">✓</span></span> container  <span class="c-dim">removed treebox-brave-otter</span></div>
+<div class="t-line" style="--d:3.7s;--run:.25s">    <span class="t-g"><span class="t-spin"></span><span class="t-check">✓</span></span> sandbox    <span class="c-dim">removed</span></div>
+<div class="t-line" style="--d:4.1s;--run:.35s">    <span class="t-g"><span class="t-spin"></span><span class="t-check">✓</span></span> worktree   <span class="c-dim">removed .treebox/worktrees/brave-otter</span></div>
+<div class="t-line" style="--d:4.7s">    <span class="c-dim">· branch     kept feature/user-auth</span></div>
+</div>
+<div class="t-scene" data-dur="5200">
+<div class="t-line" style="--d:0s;--n:10"><span class="c-ok">$ </span><span class="t-type">treebox ls</span></div>
+<div class="t-line" style="--d:0.9s"> </div>
+<div class="t-line" style="--d:1.0s">  <span class="c-dim">no worktrees yet — create one with</span> <span class="c-acc">treebox create</span></div>
+<div class="t-line" style="--d:1.8s"> </div>
+<div class="t-line" style="--d:2.1s"><span class="c-ok">$ </span><span class="t-cur"></span></div>
+</div>
+</div>
 </div>
 
 No branch name needed up front: each worktree gets its own directory and a
@@ -140,7 +193,7 @@ Docker isolation needs exactly one extra thing: Docker — see
 ```bash
 treebox doctor                       # verify the host is ready
 treebox create                       # provision + launch claude (name generated)
-treebox enter brave-otter --harness codex   # re-enter later, pick agent per entry
+treebox enter brave-otter --harness codex   # re-enter later; -H overrides the recorded harness for this session
 treebox list                         # what exists, what's stale
 treebox teardown brave-otter --delete-branch
 ```

{treebox-0.3.0 → treebox-0.4.0}/docs/install.md

@@ -118,6 +118,7 @@ The `install.sh` script reads a few environment variables:
 ```bash
 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 + tests + live host-runner smoke
+./scripts/validate.sh                 # lint + format + tests + live host-runner smoke
 ```

{treebox-0.3.0 → treebox-0.4.0}/docs/javascripts/treebox.js

@@ -4,30 +4,36 @@
  * 2. Console code blocks: the Material copy button copies only the
  *    `$ `-prefixed commands, never the output printed under them.
  * 3. ✓ / ✗ marks in console output get their CLI colors.
- * 4. The hero terminal replays its `treebox create --isolation docker` run in a loop,
- *    starting when it scrolls into view. Without JS or with reduced
- *    motion, the static final frame shows instead.
+ * 4. The hero terminal plays the full treebox lifecycle in a loop — create,
+ *    enter (codex), ^C, enter (claude), ls, rm, done — one .t-scene per
+ *    command, each shown for its data-dur, starting when the terminal
+ *    scrolls into view. Without JS or with reduced motion, the first
+ *    scene shows as a static frame instead.
  * 5. A "Copy page" button at the top of every page copies that page's raw
  *    Markdown source (embedded by hooks/copy_page.py) — an agent-ready copy,
  *    entirely offline.
  */
 (function () {
-  var PLAY_MS = 7000; // last line lands at ~6.9s
-  var HOLD_MS = 3800; // linger on the final frame before replaying
-
   function animateTerminals() {
     document.querySelectorAll(".tx-terminal").forEach(function (term) {
       if (!term.querySelector(".tx-screen") || term.dataset.anim) return;
       term.dataset.anim = "1";
       if (window.matchMedia("(prefers-reduced-motion: reduce)").matches) return;
+      var scenes = term.querySelectorAll(".t-scene");
+      if (!scenes.length) return;
       term.classList.add("tx-anim");
 
-      function play() {
-        if (!term.isConnected) return;
-        term.classList.remove("is-playing");
-        void term.offsetWidth; // reflush so the animations restart from 0
-        term.classList.add("is-playing");
-        setTimeout(play, PLAY_MS + HOLD_MS);
+      function show(i) {
+        if (!term.isConnected) return; // page swapped out — stop the loop
+        scenes.forEach(function (s) {
+          s.classList.remove("is-on");
+        });
+        void term.offsetWidth; // reflush so the scene's animations restart from 0
+        scenes[i].classList.add("is-on");
+        var dur = parseInt(scenes[i].getAttribute("data-dur"), 10) || 5000;
+        setTimeout(function () {
+          show((i + 1) % scenes.length);
+        }, dur);
       }
 
       var io = new IntersectionObserver(
@@ -35,7 +41,8 @@
           entries.forEach(function (e) {
             if (e.isIntersecting) {
               io.disconnect();
-              play();
+              term.classList.add("is-playing");
+              show(0);
             }
           });
         },