rig | API surf

rig

Sets up the workspace for a piece of work: a worktree, the diff, and a prompt file linking the right guides.

What is rig?

rig is the setup step before an agent starts work. It creates the git worktree, saves the diff, and writes a prompt file that links your guides. Everything it writes goes into a DEV/ folder in the project, which rig clean deletes.

Installation

Needs Node.js 20.12+ and git.

bash

npm install -g @apisurf/rig
rig --version

Create ~/.apisurf/rig.config.json, then run rig init to create the folders it names.

~/.apisurf/rig.config.json

{
  "worktreesPath": "/Users/you/worktrees",
  "guidesPath": "/Users/you/guides"
}

Field	Used by	What it is
`worktreesPath`	`rig wt`	Where worktrees are created
`guidesPath`	`rig prompt`	Folder of reusable guides

Set only the ones you need.

Worktrees

Each worktree goes to <worktreesPath>/<repo>/<branch>, with / in the branch name turned into -. Parallel agents each get a clean checkout without cloning again.

bash

rig wt new <source_branch> <dest_branch>  # new branch off origin/<source_branch>
rig wt new-remote <branch>                # fetch, then check out origin/<branch>
rig wt ls                                 # list a project's worktrees
eval "$(rig wt cd)"                       # jump into a worktree
rig wt cp <paths...>                      # copy files/folders into a worktree
rig wt rm [worktrees...]                  # remove some (pick from a list if none given)
rig wt rmall                              # remove all of this repo's worktrees

cp keeps each path where it sits in the repo. rm and rmall ask before removing anything.

Diffs

bash

rig diff                               # pick: staged, vs a branch, or vs a commit
rig files                              # list files a saved diff touches, with +/- counts
rig files DEV/diffs/diff-branch-002.txt

rig diff saves staged changes, or your working tree compared with a branch or one of the last 50 commits. Each diff goes to a new numbered file in DEV/diffs/, so earlier ones are never overwritten. Lists are searchable as you type. rig files with no argument lets you pick a saved diff.

Guides and prompts

A guide is a markdown file of conventions or context for the agent. rig reads <guidesPath>/<folder>/*.md. It skips folders that start with _ and any README.md.

guides

guides/
├── backend/
│   ├── api-setup.md
│   └── database.md
└── frontend/
    └── components.md

rig prompt (or rig p) asks you to pick guides, then diffs, then plans. It copies the chosen guides into DEV/doc/ and writes a numbered DEV/prompt-NNN.md that links everything you picked. If a guide is already in DEV/doc/, rig keeps that copy, so your edits to it stay. The prompt ends with a TASK_DESCRIPTION_HERE placeholder for you to replace.

a project during a task

DEV/
├── doc/            # guides copied in by rig prompt
├── diffs/          # diff-staged-001.txt, diff-branch-002.txt, ...
├── plans/          # your own plan files
└── prompt-001.md   # the file you hand the agent

A typical pass

bash

rig wt new main feature-x     # a worktree to work in
eval "$(rig wt cd)"           # go there
rig diff                      # capture what changed so far
rig prompt                    # pick guides + that diff -> DEV/prompt-001.md
# write the task into DEV/prompt-001.md and hand it to the agent
rig clean                     # remove DEV/ when the work lands