Switch dev sandbox from tmux to zellij

Replaces the tmux-based `min run dev` layout with zellij: a 2-pane
session (Claude + interactive shell) plus a banner pane that prints
the available `min run <task>` shortcuts. Adds a `fast-rs-debug`
task, a sandbox-scoped CLAUDE.md, and expands the README dev section
to cover the host/sandbox CLI naming split.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: jakeyrg

CLAUDE.md

@@ -0,0 +1,34 @@
+
+# You are in a Minimal execution environment
+
+You are running in an isolated sandbox/execution-environment specialized for software development. This environment has access to a few specialized tools to help you accomplish your goals.
+These tools are all subcommands of the `min` command.
+
+You will NOT be able to mutate the _host_ system with `apt-get`, `sudo pip install` etc, however you
+will be able to install additional commands using the `min add <packages>` command.
+
+## Adding packages: `min add <package name>`
+
+This command installs the package with the given name into your environment, letting you use the CLI tools or libraries it encapsulates.
+
+Without any flags, `min add` installs the given package for this session only. If you are sure that it will
+always be needed as a build-time (i.e. tools needed during compilation) or runtime dependency (i.e. dynamic
+libraries), you can add `--build` or `--runtime` to the invocation to depend on the package permanently.
+
+Help string for `min add`: min add [--session|--build|--runtime|--task <taskname>] <packages>
+
+Examples:
+
+ * The `curl` utility is needed: `min add curl`
+ * This project links against openssl: `min add --runtime openssl`
+ * This project has a build step requiring the protobuf compiler: `min add --build openssl`
+
+## Finding packages: `min search <search term>`
+
+Performs a text search across all available packages, printing packages that match or partially match the given term. Use this to find the exact names of packages you need.
+
+## Running tasks: `min run <task name>`
+
+This command runs the specified task (declared in this project's `minimal.toml`) in a separate Minimal execution environment, streaming back the output.
+
+Some typical tasks include `build` and `test`.

README.md

@@ -68,6 +68,8 @@ To compile a slim binary without the TUI:
 
 ## Building
 
+From the host:
+
     minimal run build
 
 The release binary lands at `target/release/fastrs`. Or run directly:
@@ -76,15 +78,39 @@ The release binary lands at `target/release/fastrs`. Or run directly:
 
 ## Development
 
-`minimal.toml` defines tasks that run inside the [Minimal](https://minimal.dev) sandbox with the toolchain pinned:
+This project is set up to build and run inside the [Minimal](https://minimal.dev) sandbox — the toolchain (`rust`, `gcc`, `binutils`, …) is pinned in `minimal.toml`, so no host install is required beyond the `minimal` CLI.
+
+> **CLI naming:** on the host the binary is `minimal`. Once you're inside a sandbox (e.g. via `minimal run dev`) the same tool is exposed as `min`. The examples below use whichever name matches the context.
+
+Tasks are defined in `minimal.toml`. From the host:
 
-    minimal run dev          # interactive tmux session (Claude + shell)
+    minimal run dev          # interactive zellij dev session (Claude pane + shell pane)
+    minimal run build        # cargo build --release
+    minimal run run          # cargo run --release
+    minimal run fast-rs-debug # cargo run --release with RUST_LOG=debug
     minimal run test         # unit tests
     minimal run test-live    # also run the live integration test against fast.com
     minimal run lint         # cargo clippy --all-targets -- -D warnings
     minimal run fmt          # cargo fmt
 
-Without Minimal, the equivalent cargo commands (`cargo build --release`, `cargo test`, `cargo clippy --all-targets -- -D warnings`, `cargo fmt`) work too.
+From inside the sandbox shell, drop the `imal`:
+
+    min run test
+    min run lint
+    # etc.
+
+### `minimal run dev`
+
+Launches a [zellij](https://zellij.dev) layout (`zellij.kdl`) via `scripts/setup-dev.sh` with two panes:
+
+- **left** — Claude Code (`claude --dangerously-skip-permissions`, only safe because the sandbox is ephemeral).
+- **right** — a bash shell that first runs `scripts/dev-shell.sh` (a quick cheat sheet of available `min run <task>` shortcuts) and then drops you into an interactive prompt.
+
+The session is named `dev` and is reset on each invocation.
+
+### Without Minimal
+
+The equivalent cargo commands (`cargo build --release`, `cargo test`, `cargo clippy --all-targets -- -D warnings`, `cargo fmt`) work too.
 
 CI runs `cargo test --lib`, `cargo fmt --check`, and `cargo clippy --all-targets -- -D warnings` on Linux/macOS/Windows. Tagged pushes (`v*`) build cross-platform release archives via `.github/workflows/release.yml`.
 

minimal.toml

@@ -20,11 +20,14 @@ exec = "bash --noprofile -l"
 [tasks.claude]
 packages = ["base", "claude-code"]
 exec = "claude --dangerously-skip-permissions"
+patches.dir."~/.claude" = "read-write"
+patches.file."~/.claude.json" = "read-write"
 
 [tasks.dev]
 interactive = true
-packages = ["claude-code", "base", "vim", "tmux", "ncurses", "fd", "fzf", "ripgrep", "git", "jq", "rust"]
+packages = ["claude-code", "base", "vim", "zellij", "fd", "fzf", "ripgrep", "git", "jq", "rust"]
 patches.dir."~/.claude" = "read-write"
+patches.file."~/.claude.json" = "read-write"
 patches.file."~/.gitconfig" = "read-only"
 patches.file."~/.vimrc" = "read-write"
 bash = "scripts/setup-dev.sh"
@@ -52,3 +55,7 @@ exec = "cargo fmt"
 [tasks.run]
 packages = ["base", "rust", "gcc", "binutils"]
 exec = "env RUSTFLAGS=-Clinker=gcc CC=gcc cargo run --release"
+
+[tasks.fast-rs-debug]
+packages = ["base", "rust", "gcc", "binutils"]
+exec = "env RUSTFLAGS=-Clinker=gcc CC=gcc RUST_LOG=debug cargo run --release"

scripts/dev-shell.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# Banner pane for `min run dev`. Prints the project label + task shortcuts,
+# then sleeps to keep the pane alive (the interactive shell lives in the
+# sibling pane below).
+
+if [ -t 1 ]; then
+  R=$'\e[0m'    ; D=$'\e[2m'    ; B=$'\e[1m'
+  CY=$'\e[38;5;87m'              # cyan      — brand
+  PK=$'\e[38;5;213m'             # pink      — section headers
+  GY=$'\e[38;5;245m'             # grey      — chrome
+  GR=$'\e[38;5;120m'             # green     — accent
+  YL=$'\e[38;5;221m'             # yellow    — caution
+fi
+
+cat <<EOF
+
+  ${CY}█▀▀ ▄▀█ █▀ ▀█▀ █▀█ █▀${R}    ${GR}⚡${R} ${D}pure-Rust fast.com speed test${R}
+  ${CY}█▀  █▀█ ▄█  █  █▀▄ ▄█${R}    ${D}you're inside the${R} ${B}Minimal${R} ${D}sandbox${R}
+  ${GY}────────────────────────────────────────────────────────${R}
+
+  ${PK}▸ tasks${R}  ${D}(each spawns a fresh sub-sandbox)${R}
+    ${B}min run build${R}            ${D}cargo build --release${R}
+    ${B}min run run${R}              ${D}cargo run --release${R}
+    ${B}min run fast-rs-debug${R}    ${D}cargo run --release w/ RUST_LOG=debug${R}
+    ${B}min run test${R}             ${D}cargo test${R}
+    ${B}min run test-live${R}        ${D}cargo test -- --ignored${R}  ${YL}(hits fast.com)${R}
+    ${B}min run lint${R}             ${D}cargo clippy --all-targets -- -D warnings${R}
+    ${B}min run fmt${R}              ${D}cargo fmt${R}
+
+  ${PK}▸ sandbox${R}
+    ${B}min add${R}  ${GY}<pkg>${R}       ${D}install a package for this session${R}
+    ${B}min search${R} ${GY}<term>${R}    ${D}find a package by name${R}
+
+  ${GY}quit zellij: ${R}${B}Ctrl-q${R}   ${GY}·   detach: ${R}${B}Ctrl-o${R} ${GY}then${R} ${B}d${R}
+
+EOF
+
+exec sleep infinity

scripts/setup-dev.sh

@@ -10,9 +10,15 @@ if [ "${IS_SANDBOX:-}" != "1" ]; then
   exit 1
 fi
 
-tmux -f tmux.conf new-session -d -s dev
-tmux send-keys -t dev 'claude --dangerously-skip-permissions' Enter
-tmux split-window -t dev -h 'bash'
-tmux select-layout -t dev even-horizontal
-tmux select-pane -t dev:0.0
-tmux attach-session -t dev
+# The sandbox terminfo db has no xterm-ghostty entry, so `clear` (and any
+# other terminfo consumer) errors out. Override before zellij starts so
+# child panes inherit a known TERM.
+export TERM=xterm-256color
+
+# Kill any prior `dev` session so each run starts from a clean layout.
+zellij delete-session --force dev 2>/dev/null || true
+
+zellij --config zellij-config.kdl --layout zellij.kdl attach --create dev
+
+# Wipe zellij's "Bye from Zellij!" trailer.
+clear

tmux.conf

@@ -0,0 +1,2 @@
+show_startup_tips false
+show_release_notes false

zellij-config.kdl

@@ -0,0 +1,13 @@
+layout {
+    pane split_direction="vertical" {
+        pane focus=true name="claude" command="claude" {
+            args "--dangerously-skip-permissions"
+        }
+        pane split_direction="horizontal" {
+            pane size="35%" name="fastrs" command="scripts/dev-shell.sh"
+            pane name="shell" command="bash" {
+                args "--noprofile" "-l"
+            }
+        }
+    }
+}