using-wt

📁 abhi-arya1/wt 📅 Feb 8, 2026

总安装量

周安装量

#74873

全站排名

安装命令

npx skills add https://github.com/abhi-arya1/wt --skill using-wt

Agent 安装分布

amp 2

gemini-cli 2

github-copilot 2

codex 2

kimi-cli 2

opencode 2

Skill 文档

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        # Create from current repo
wt enter my-experiment        # Shell in
wt rm my-experiment           # Clean up

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      # local:3000 -> remote:8080
wt host map prod 5432 5432      # forward postgres
wt enter my-feature             # mappings applied automatically
wt host unmap prod 3000         # remove mapping

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.

GitHub 仓库 ↗ ← 返回陌讯 Skills 聚合平台