| name | using-wt |
| description | Manages git worktree-based sandboxes with the wt CLI tool, both locally and on remote hosts over SSH. Use when the user wants to create, enter, run commands in, list, remove, or manage isolated worktree sandboxes, configure remote hosts, or troubleshoot wt issues. |
wt — Git Worktree Sandbox Manager
CLI tool that creates isolated git worktree checkouts ("sandboxes") locally or on remote SSH hosts. Built with TypeScript + Commander.
Core Concepts
- Sandbox: An isolated git worktree checkout with a unique name, ID (nanoid), host, and path
- Host: Either
"local" (built-in) or a registered remote SSH target
- Mirror: A bare
--mirror clone stored at .wt/mirrors/<repoId>.git (local) or <root>/mirrors/ (remote)
- Config:
~/.config/wt/config.json — stores hosts, sandboxes, default host
Directory Layout
.wt/ # Local (inside repo root, gitignored)
mirrors/<repoId>.git/ # bare --mirror clone
sandboxes/<sandboxName>/ # worktree checkout
meta/<sandboxName>.json # metadata
<remote-root>/ # Remote (user-configured)
mirrors/<repoId>.git/
sandboxes/<sandboxName>/
meta/<sandboxName>.json
Commands
| Command | Description |
|---|
wt up [name] | Create sandbox on a host. -H <host>, --branch <ref>. Auto-names from branch. |
wt local [name] | Shorthand for wt up on local host. |
wt enter <name> | Shell into sandbox. --tmux for persistent session. |
wt run <name> -- <cmd...> | Run command in sandbox. --json, --quiet. |
wt ls | List sandboxes. --host to filter. |
wt rm <name> | Remove sandbox (prompts confirmation, --yes to skip). |
wt rename <old> <new> | Rename a sandbox. |
wt status <name> | Show sandbox info (host, ref, path, age, tmux state). |
wt sessions | List active wt-* tmux sessions. |
wt gc | Remove stale sandboxes. --older-than 7d (default), --dry-run. |
wt doctor | Check prerequisites (git, bun/node, tmux) on a host. |
wt bootstrap | Report host readiness + install hints (read-only, installs nothing). |
wt host add [name] | Register remote host. Interactive mode if args omitted. |
wt host ls | List configured hosts (includes port mappings). |
wt host check <name> | Test SSH connectivity. |
wt host rm <name> | Remove host config. |
wt host map <name> <localPort> <hostPort> | Add port forwarding (-L) to a host. |
wt host unmap <name> <localPort> | Remove a port mapping. |
Common Workflows
Local sandbox:
cd my-project
wt local my-experiment
wt enter my-experiment
wt rm my-experiment
Remote sandbox:
wt host add prod --ssh user@10.0.0.5 --root /srv/wt
wt doctor -H prod
wt up my-feature -H prod --branch feature/auth
wt enter my-feature --tmux
wt run my-feature -- make build
Port forwarding:
wt host map prod 3000 8080
wt host map prod 5432 5432
wt enter my-feature
wt host unmap prod 3000
Parallel branch testing:
wt up auth --branch feature/auth
wt up payments --branch feature/payments
wt run auth -- bun test
wt run payments -- bun test
wt gc --older-than 1d
Important Conventions
- All commands support
--json for machine-readable output (errors: { "ok": false, "error": "..." })
- Host flag is
-H (capital), not -h (which is --help)
wt run uses -- to separate wt flags from the command to execute- Sandbox names auto-derive from branch name if omitted (last segment after
/, sanitized)
- Host names must match
/^[a-z][a-z0-9_-]{0,31}$/
wt up is idempotent — re-running with same name/host/repo returns existing sandbox.env* files from CWD are auto-copied into new sandboxes- Config writes are concurrency-safe — all mutations use
withConfig(fn) (proper-lockfile) in src/core/host/config.ts
Good-to-know
wt up defaults to HEAD SHA (detached), not a branch ref. Branch name is only used for naming.- Remote sandboxes require the origin to be cloneable from the remote host.
wt enter --tmux and interactive commands call process.exit() — they take over the process.- Local
.wt/ resolves from repo root via git rev-parse --show-toplevel, even from subdirectories.
