Skip to content

About

A tiny agent sandbox orchestrator

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

project-sandbox-tui

PyPI

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 (O for every run); delete and undo with dd / 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

Requirements

  • Linux or macOS (WSL on Windows)
  • Python ≥ 3.12 and uv
  • jj ≥ 0.46 on PATH; for an existing Git repository, run jj git init --colocate
  • project-sandbox ≥ 0.2.2 and Apple Containers, Docker or Podman

Getting started

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             # launch

Press ? 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.

Documentation

License

MIT

About

A tiny agent sandbox orchestrator

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Contributors

Languages