workbox (wkb)

Minimal Bun-first CLI for Git worktrees. Creates a worktree per sandbox and removes it cleanly.

Install

bun add -g @alecrust/workbox

Or via npm (still requires Bun on your PATH):

npm i -g @alecrust/workbox

Or install from GitHub:

bun add -g github:AlecRust/workbox

Use

wkb new <name> [--from <ref>]         # create sandbox worktree
wkb rm <name> [--force] [--unmanaged] [--delete-branch] # remove worktree
wkb list                              # list workbox worktrees
wkb prune                             # prune stale git worktree metadata
wkb status [name]                     # show repo/worktree info and cleanliness
wkb setup                             # run configured bootstrap steps (in current worktree)
wkb dev <name>                        # run configured dev command in a sandbox
wkb exec <name> -- <cmd...>           # run a command in a sandbox

workbox and wkb are equivalent.

Config

Looks for config in:

1. .workbox/config.toml
2. workbox.toml

Config is required. Paths are resolved relative to the repo root. worktrees.directory must resolve within the repo root.

Example:

[worktrees]
directory = ".workbox/worktrees"
branch_prefix = "wkb/"
base_ref = "main"

[bootstrap]
enabled = true
steps = [
  { name = "install", run = "bun install" },
  { name = "build", run = "bun run build" }
]

[dev]
command = "bun run dev"
# Optional (explicit opt-in): open an editor when running `wkb dev`.
# open = "code ."

Development

bun install
bun test
bun run check
bun run format

Commit conventions

Conventional Commits are enforced. See cog.toml.