rig

A minimum runtime for your agents.

One binary. One model endpoint. One terminal.

rig assembles context, streams the model, executes tool calls, returns results, and repeats. The TUI, piped CLI, headless worker, and dashboard share the same session, task, memory, and scheduler stores.

install

Choose one:

Installer (POSIX sh, no Go, no sudo; installs to ~/.local/bin):

curl -fsSL https://mrsirg97-rgb.github.io/rig/install.sh | sh

Release binary from releases/latest. Choose your <os>_<arch>:

curl -fsSL https://github.com/mrsirg97-rgb/rig/releases/latest/download/rig_linux_amd64 -o rig
chmod +x rig

go install (needs Go ≥ 1.26.6; the core is stdlib-only):

go install github.com/mrsirg97-rgb/rig/cmd/rig@latest

rig -update fetches, verifies, and atomically installs the latest release. The running process keeps the old binary until restart.

first run

./rig --base-url $ENDPOINT --model $NAME

rig needs an OpenAI-compatible SSE endpoint and a model ID. The endpoint defaults to http://127.0.0.1:8090/v1; there is no model default — a run without one refuses at start, naming the three ways to set it (--model, RIG_MODEL, the model key in settings.json). The TUI is the frontend when stdout is a terminal, the piped CLI otherwise. For scripts, run ./rig -p "the task". See docs/SETUP.md for configuration.

the tools

rig ships 18 built-in tools. Restrict them with --allow:

Every tool result is capped. Repeated identical failures are bounded. An optional round cap limits calls per turn. A failed call executes once.

plugins

A Python plugin is one file and one tool. It provides run and schema. There is no build step. Model-authored plugins land in ~/.rig/plugins/pending/. Approve, disable, and reload them with /plugins or the dashboard. See docs/PLUGINS.md.

configuration

Configuration lives in ~/.rig/. Set $RIG_HOME to move it. Every file is optional. Invalid files fail startup and name the file and field.

Each key resolves in this order: flag, environment, file, built-in default. /models lists and switches models. /effort changes reasoning effort. See docs/SETUP.md for configuration and sandbox settings.

the dashboard

rig serve

The dashboard serves the rig stores on loopback only. On first run it prints an access token, stores it with mode 0600, and includes it in the URL. The page exchanges the token for a cookie. Mobile friendly.

• sessions: list them per workspace, and resume one mid-work
• todo: the queue, with create, start, complete, and retry
• scheduler: the jobs, with create, pause, resume, remove, an in-place update form that opens with the job's current fields, and each job's run audit trail
• models: the table, with the effort dial
• plugins: approved, pending, disabled; the forge reads and saves a plugin's source into the pending zone

docs

layout

cmd/rig      composition root; wires every seam once; flags and env only
core            the seams, wire types, and the streaming-event vocabulary
loop            the concrete turn runtime (fault/cancel-aware)
evt             the event loop (SPEC_EVT): one consumer, many producers; the
                turn runtime's engine
kernel.go       the composition kernel
command/        the user commands (/compact, /models, /sessions, /effort, ...)
config/         the four-layer config resolution (flag > env > file > embedded)
models/         the per-model table (window, compaction numbers, role, effort)
policy/         ContextPolicy implementations: compact (per-model trigger),
                effort (the reasoning dial's provider decorator)
middleware/     ToolMiddleware: toolset (the live table), approve (the gate),
                paths (the ~ boundary), perm (deny by default + plugin
                provenance), guard (the bound, the round cap, the result cap)
provider/       Provider implementations (the openai-compatible SSE adapter)
plugins/        python plugin discovery (one file, one tool) and the plugin
                door (run/schema) and the ecosystem (list/create/delete/reload)
store/          the SQLite stores (state, todo, rem, scheduler), the sqlx
                transaction seam, the project scope identity (store/scope);
                -resume projects a session back from the state rows
tool/           Tool implementations: bash(1); file read/write/edit; fs
                ls/find/grep; todo the job queue; rem memory; scheduler
                background jobs; delegate the one-shot worker; python the
                persistent IPython kernel; web search and fetch; diff the
                observation diff; sessions the soak's vitals
frontend/       Frontend implementations: cli (the piped reference), tui (the
                terminal default), oneshot (-p worker), web (the serve
                dashboard)
specs/          the specs, written and agreed before the code (SPEC_CORE first)
docs/           DESIGN (architecture), SETUP (build/config), USAGE (running),
                PLUGINS (the python plugins)

extending

The structural test is simple: add one file and one registration line. The loop never names a concrete tool, provider, policy, frontend, or middleware. A Python plugin needs no Go. See docs/DESIGN.md, docs/PLUGINS.md, and CONTRIBUTING.md for the process.

under the hood

core/ and loop/ use only the standard library. Stores use the pure-Go modernc.org/sqlite driver.