Detached sandboxes for AI agents. Pull any branch into a throwaway, fully-working environment in seconds — run anything in it, see what's running, and surgically patch any branch without ever checking it out.
Built for agents that need to touch a branch other than the one in your working tree — to test a fix, run a build, or land a commit — without disturbing your current checkout.
Named
rigd("rig daemon"). A rig is a workstation you operate; rigd hands an agent a whole other one.
An AI agent working in your repo constantly hits the same wall: the thing it needs to change isn't checked out, and switching branches (or spinning a worktree by hand) is slow and clobbers your state. rigd splits the job into two purpose-built tools:
- box — a real, detached worktree with your dependencies symlinked in. Instant to create, and tests / typecheck / git hooks all work because the deps are already there. The agent's "other computer."
- touch — commit to any feature branch on origin using git plumbing, with no checkout at all (the default branch is refused). Surgical, instant, zero footprint.
Your working tree, your current branch, and your uncommitted work are never touched.
rigd runs straight from its TypeScript source — no build, no runtime dependencies. It only needs Node ≥ 22.6 (which strips types natively).
git clone <repo> ~/Desktop/Projects/rigd
cd ~/Desktop/Projects/rigd
npm link # puts `rigd` on your PATHOr run it in place without linking:
node ~/Desktop/Projects/rigd/src/cli.ts --help# Create a detached box from a repo (defaults to origin/main)
rigd up ~/code/myapp --name fix-login
# ...or from the current repo
cd ~/code/myapp
rigd up --base origin/main
# See your boxes
rigd ls
# Re-sync a box to the latest of its base (fetch + reset)
rigd sync fix-login
# Run a command inside the box
rigd run fix-login -- pnpm test
# Start a long-running process (dev server) and see what's running
rigd spawn fix-login -- pnpm dev
rigd ps fix-login
# Surgically commit a file to any branch on origin — no checkout
rigd touch fix-login feature/x -m "fix typo" -f src/app.ts
# Tear it down
rigd down fix-loginNo config file required. Boxes and their state live under ~/.rigd.
When you run rigd up:
- Resolves the source repo from the path you give (or the current directory).
- Creates a detached git worktree at the base ref (
origin/mainby default) — detached, so many boxes can sit on the same branch's content at once. - Symlinks your dependencies (
node_modules, plus eachapps/*/packages/*node_modules) and root env files from the source repo. No install — the box is usable immediately. - Registers the box so you can list, sync, run processes in, and remove it.
You can have many boxes per repo and boxes across different repos at the same time — each fully isolated, each instant on reuse.
| Concept | What it is |
|---|---|
| box | A detached worktree (git worktree add --detach, default origin/main) with deps symlinked in. The unit you run things in. |
| process | A command launched inside a box, tracked so you can list, tail, and stop it. |
| loose commit | A commit made in a box's detached HEAD — recorded per box with append-only recovery refs, so detached commits are never lost or confused. |
| touch | Patch any feature branch directly via git plumbing (blob → tree → commit → push), with no working tree. |
A git branch can be checked out in only one worktree at a time — try to put main in a second worktree and git refuses. By detaching at origin/main, a box sits at main's commit without owning the branch label, so you can run many boxes on main's content simultaneously.
Two rules keep detached safe:
rigd syncrefuses to strand work. It re-points the box to the latest base (fetch + reset — the detachedgit pull, no merge noise), but only when the box is clean. If it has uncommitted changes or commits not yet in its base, sync stops and tells you;--forceresets anyway.- Loose commits are reconciled, not lost. rigd protects a box's detached commits with append-only recovery refs under
refs/rigd/<box>/…(commit/downwrite them; a forcedsync/checkoutsnapshots before abandoning) — so detached work is tracked per box, surfaced bycommits, and never silently garbage-collected.
For everything that touches files — editing, running tests, starting a dev server — a detached box behaves exactly like a normal origin/main checkout.
All commands below are implemented (✅).
Create a detached box.
| Option | Description |
|---|---|
[repo] |
Path to (or inside) the source repo. Defaults to the current directory. |
--base <ref> |
Ref to detach at. Defaults to the remote's actual default branch (origin/main, origin/master, origin/develop, …), detected from origin/HEAD. Accepts a branch, tag, or sha. |
--name <id> |
Box id (and directory name). Auto-derived from the repo name (myapp, myapp-2, …) when omitted. Must be ref/path-safe (letters digits ._-); a name with spaces/:/~ is rejected, an auto-derived one is sanitized — a bad id would corrupt the box's refs/rigd/<id>/… recovery refs. |
--json |
Print the created box as JSON (for agents/scripts). |
rigd up ~/code/myapp --base origin/main --name fix-login
# ✓ box "fix-login" ready
# path: ~/.rigd/boxes/fix-login
# base: origin/main @ a1b2c3d4e5 (detached)
# linked: node_modules, apps/web/node_modules, apps/api/node_modulesList boxes — id, base, head commit, running-process count, and path.
Switch what a box tracks — a detached checkout to any branch/tag/sha. A bare branch name that exists on the remote (e.g. dev, feature/x) is normalized to origin/<name> and fetched, so the box tracks the remote and sync refreshes it; a sha/tag/origin/… ref is used as-is. The ref becomes the box's new base, so this is how a box roams branches while staying detached. Refuses if switching would strand uncommitted or unpushed work; --force overrides. (Aliased as co.)
Fetch the box's base and detached-reset to it — the safe "get latest" for a detached box. Refuses if the box has uncommitted changes or commits not yet in its base (resetting would move off them); --force resets anyway. The fetch is required when the base is a remote branch — if the remote is unreachable, sync fails loudly rather than silently resetting to a stale local copy.
Remove a box's worktree and registry entry. Prunes recovery refs whose work is already on a remote (so reusing the id later is pristine) but keeps — and warns about — any holding unpushed work, so nothing is lost. --force removes even with uncommitted changes.
Run a command inside the box, wait, print stdout/stderr, and exit with the command's code. --timeout <s> kills a command that runs too long (SIGKILL) and exits 124 — so a hung test or an accidental pnpm dev can't freeze the agent's turn. A command killed by a signal (OOM, kill) exits 128 + signum (e.g. 143 for SIGTERM) — never a misleading 0 — so a killed test/build can't look green. --json returns {stdout, stderr, code, signal?, timedOut?} for agents. For short commands: tests, typecheck, git, scripts. (Use -- so the command's own flags aren't parsed by rigd.)
Start a long-running process (dev server, watcher) in the background — detached and unref'd, so it outlives the rigd call. Output streams to a per-process log; returns a process id (p1, p2, …).
Show what's running on a box — id, status (reconciled live from the OS), pid, command.
Print a process's captured output, or follow it with -f.
SIGTERM a running process and mark it exited.
Commit on the box's detached HEAD. --all stages tracked modifications (it skips new files — you'll be warned); --add-all stages everything incl. new/deleted files. --amend rewrites the top commit instead of adding one (message optional — omit to keep it); the pre-amend commit is first stamped to an append-only recovery ref, so it's never lost. Protects the lineage with a recovery ref (refs/rigd/<box>/head). Hooks run (deps are symlinked); --no-verify skips them.
Ship the box's detached HEAD straight to origin/<name> (git push origin HEAD:refs/heads/<name>) — no local branch, box stays detached. Guards:
--forceonly works on a branch THIS box pushed — it leases against your last push (--force-with-lease), so it refuses if a concurrent writer moved the branch, and fails closed on any branch the box doesn't own (can't clobber unseen work).--expect <sha>is the escape hatch for force-pushing a branch this box didn't push — e.g. a PR branch a later box rebased. You name the tip you've seen (fromcheckout/commits); it's still a lease, so a stale--expect(someone moved the branch since) is refused, never clobbered. The sha must be present locally — fetch it first (rigd checkout origin/<branch>).- Refuses the default/protected branch (
main/master/origin's default) — that's what PRs are for. - Refuses an empty push (no commits beyond base; nothing to ship).
--propens a pull request viagh(best-effort; the push succeeds regardless).
The box's commits ahead of base — each flagged [pushed] (already on a remote) or [local] — plus any abandoned lineages still held by recovery refs, so work that a forced sync/checkout reset off (or a removed box left behind) stays visible and recoverable, never silently lost.
Patch an existing origin branch with no checkout — git plumbing builds blob → tree → commit on top of the branch tip in a throwaway index and pushes it. -f writes a box file's content onto the branch; --rm deletes a file from it (must currently exist on the branch). At least one -f or --rm is required. The box's HEAD never moves. Refuses the default/protected branch and no-op patches; preserves each file's mode; rejects paths that escape the box and refuses symlinks (touch copies file content, so a symlink would deref and write its target's bytes onto the branch); needs a git identity; and warns when it overwrites existing differing content on the branch (touch sets content — it doesn't merge). See How touch works.
The trick that makes boxes instant. A box is a git worktree, so its node_modules (gitignored) starts empty. Instead of running install, rigd symlinks the source repo's already-installed deps into the box:
- root
node_modules,.env,.env.local - every
apps/*/node_modulesandpackages/*/node_modulesthat exists
Because the deps are real and present, tests, typecheck, and husky/lint-staged hooks all run in the box with no setup.
Monorepo caveat: in a pnpm/yarn workspace, a box's cross-package imports (@yourscope/*) resolve through the source repo's node_modules, i.e. the source repo's copy of that package — not the box's. This is fine for editing and testing within one app (the common case). It only matters if you edit a shared package and a consumer in the same box and expect live linkage between them.
Two distinct ways a change leaves a box — don't confuse them:
Path A — box-native (your work → a branch). The box edited real files (and maybe ran tests). You commit on its detached HEAD (a loose commit, tracked per box), then push --branch <name> ships HEAD straight to a remote branch. The box never owns a branch; it stays detached.
Path B — touch (these files → that branch). Surgically set specific files onto any origin branch via plumbing — no box HEAD, no checkout, one commit. For quick patches where you don't need to run anything.
| ships | uses box HEAD? | needs a machine? | |
|---|---|---|---|
| push | the box's whole commit lineage as a branch | yes | yes (you worked in it) |
| touch | one commit of specific files onto a branch | no | no |
rigd up → edit → rigd run -- pnpm test → rigd commit → rigd push --branch X → PR
└─ or rigd touch X for a quick patch
touch edits a branch with no copy of the repo on disk, using git's object model directly:
- Save your new file content as a git blob.
- Build a new tree = the branch's tree with your file(s) swapped in.
- Wrap it in a commit whose parent is the branch tip.
- Move the branch ref to the new commit and push.
The result is one clean commit on the branch, touching exactly your files — and nothing was ever checked out. It's the right tool when you don't need to run anything, just land a change. (To run tests first, use a box.)
touchsets file content — it does not merge. Your file is written onto the target branch's tree as-is; if the branch had its own version, yours replaces it. Use it for surgical, known-content patches, not for reconciling divergent edits.
~/.rigd/
registry.json # all boxes (id, repo, base, head, processes, commits, pushed)
boxes/<id>/ # each box's detached worktree
logs/<id>/ # per-process logs
Override the root with RIGD_HOME (handy for tests or throwaway runs):
RIGD_HOME=/tmp/rigd-test rigd up . --name scratchA corrupt registry.json won't brick rigd — it falls back to empty and the worktrees on disk remain the source of truth.
- Every read command supports
--jsonfor structured output. - Commands exit non-zero with a
✗ <message>on stderr, so failures are easy to detect. - All git calls use argument arrays (never shell strings) — no injection surface from branch names or paths.
- Boxes are addressable by stable id, so an agent can create a box, run several commands in it across turns, and tear it down.
sync/checkoutrefuse to strand work — they stop if the box has uncommitted or unpushed changes.--forceoverrides (and can discard).down --forcediscards uncommitted work too.push --forcecan't clobber what the box doesn't own — force only works on a branch this box pushed (leasing against its last push), fails closed otherwise, refuses if a concurrent writer moved the branch, and always refuses the default/protected branch. Prevents clobbering teammates or main.- Process tracking is pid-based. rigd verifies a pid is genuinely the process it spawned (by start time), so a reused pid is never mistaken or wrongly signalled — but tracked processes don't survive a machine reboot.
stopsignals the whole process group, so wrapper commands (pnpm dev, etc.) are fully stopped, grandchildren included. - Recovery refs. Detached lineages are protected under
refs/rigd/<box>/*(in the source repo).downre-fetches + prunes, then drops the refs already on the remote and keeps (warns about) unpushed ones, so a removed/reused id is clean. "Already on the remote" is confirmed against a freshly fetched mirror, not a stale local one; if the remote is unreachable,downfails closed and keeps every ref. A long-lived box still accumulatesabandoned-*refs across forced resets — deliberate (never lose work); prune them manually when safe:git for-each-ref refs/rigd/<box>thengit update-ref -d <ref>. - Detached HEAD warnings are expected — that's the design. Recovery refs keep commits safe.
git branch --show-currentis empty inside a box (it's detached). A tool that demands a branch name won't find one.- Symlinked deps mean the box shares the source repo's installed packages. If you change versions in the source repo, boxes see it immediately.
- The registry is safe under parallelism. Writes are atomic (temp file + rename) and mutations take a short file lock, so concurrent boxes can't drop each other's entries or leave a half-written
registry.json. (A stale lock from a crashed command is auto-reclaimed after 15s.) The one residual race is two commands mutating the same box at the same instant — don't do that.
- Node ≥ 22.6 — runs the TypeScript source directly via Node's type stripping. No build step, no runtime dependencies.
- git with worktree support (2.5+).
- ✅ Slice 1 — boxes:
up,ls,checkout,sync,down, dependency symlinking, registry, and the safety guards (sync/checkout refuse unpushed work, down warns). - ✅ Slice 2 — processes:
run,spawn,ps,logs,stop. - ✅ Slice 3 — commit & push:
commit,push(HEAD → branch;--force-with-lease, refuses default/empty), loose-commit reconciliation + recovery refs (commits). - ✅ Slice 4 — touch: no-checkout branch patching (refuses default/no-op, preserves mode).
All slices shipped — rigd is feature-complete.
MIT