A vim/ranger-style terminal UI for running coding agents in project-sandbox containers, with one sandbox per jj bookmark.
🤖 Written largely by AI, reviewed by a human. Use at your own risk.
- Run agents interactively or in the background with completion notifications.
- Save agent, model and sandbox options as named profiles, selectable in launch forms.
- Review changes commit by commit, with shared seen marks and your place remembered during the TUI session.
- Merge or rebase tasks from separate jj workspaces with agent assistance.
- Follow each bookmark's prompts and merges in a history graph (
Ofor every run); delete and undo withdd/u. - Run shell or configured commands in the foreground (
:!make,:test), once in the repository background (:&test), or in each selected workspace (:*test); see the command comparison. Map any form to leader keys. - Let project-sandbox handle isolation, credentials and workspace teardown.
sbx-tui ~/workspace/myproject 5 bookmarks · 1 running
bookmark vs main reviewed head subject status
@ working copy ● ↑1 qzmvtlno (no description set)
▶─╮ merge/parser-tui ↑6 Δ9 0/9 wnrtlxqz Merge feature/parser, spike… merging
✓ │ feature/parser ↑3 Δ5 5/5 sutnpmvo Add streaming parser completed
│ ✗ spike/tui ↑2 ↓1 Δ4 1/4 zsuskuln Try a ranger-style layout failed (1)
│ │ ○ fix/flaky-tests ↑1 Δ2 0/2 rlvkpnrz Stabilise integration tests
○─┴─╯ main ● = kxyrwpsn Initial import
- Linux or macOS (WSL on Windows)
- Python ≥ 3.12 and uv
- jj ≥ 0.46 on
PATH; for an existing Git repository, runjj git init --colocate - project-sandbox ≥ 0.2.2 and Apple Containers, Docker or Podman
uv tool install project-sandbox
uv tool install project-sandbox-tui
# For latest from Github:
# uv tool install git+https://github.com/pkrusche/project-sandbox-tui
# From a checkout: uv tool install . (or uv sync && uv run sbx-tui)
cd ~/workspace/myproject
sbx-tui --init # detect the project type, write config and install a local setup skill
sbx-tui doctor # check dependencies, runtime and configuration
sbx-tui --dry-run # preview project-sandbox calls
sbx-tui # launchPress ? for full help.
Highlight @ or a feature bookmark and press i for an interactive sandbox
session or r to run or queue a background prompt (L manages the queue).
Use :config-profiles to save an agent setup,
then choose it in either launch form. Select custom to adjust settings for a run.
See initialization for project detection
and the local sbx-tui-config setup skill. Existing config and skill files are
preserved.