riffer-rig
riffer, in your terminal and in your process.
riffer-rig is a general-purpose agent for Ruby developers who want to own their harness. It runs in your terminal, and because the runtime is separate from the terminal it also runs inside any Ruby process: a Rails app, a script, a job. You extend it in Ruby — tools, commands, providers and hooks are ordinary classes on riffer's primitives, and the same objects work in the terminal and in your app.
It ships with a coding toolkit (read, write, edit, bash) because a shell and file access get almost any task done, but nothing in its prompt makes it a coding agent. Tools run without asking for permission; see what runs without asking.
Install
Requires Ruby 4.0 or later.
gem install riffer-rig
Quickstart
cd my-project
riffer
The first run asks for a model as provider/name — for example anthropic/claude-sonnet-4-6 — and then for that provider's API key, and saves both under ~/.riffer/. gemini/… models work straight away; other providers' SDK gems are offered for install on first use.
Type a prompt and press Enter. /help lists the commands, and Getting started walks through a first session.
Extend it
An extension is a Ruby block in ~/.riffer/rig.rb (every project) or .riffer/rig.rb (one project):
Riffer::Rig.extension('git') do |rig|
rig.command('log', description: 'Recent commits') { |ctx| ctx.say `git log --oneline -n 10` }
rig.prompt(:branch) { "Current branch: #{`git branch --show-current`}" }
end
That adds a /log command and puts the current branch in the system prompt on every turn. Extensions can also add tools, hooks, skills, MCP servers, settings and providers — Extensions starts with a complete tool.
Embed it
runtime = Riffer::Rig::Loader.runtime(cwd: Dir.pwd, host: Riffer::Rig::Hosts::Null.new)
puts runtime.ask('why is this test failing?').content
This builds the same agent the terminal does, from the same settings, credentials and extensions. Embedding covers streaming, cancelling, snapshots and reloading.
Documentation
The guides are at https://riffer.bottrall.dev, and their sources are in docs/. Good places to start:
- Overview — what riffer-rig is and how it fits together
- Configuration — settings and where each value comes from
- Command line — every flag
- Headless mode — one prompt from a script or CI job, with exit codes and an NDJSON stream
- ACP — riffer-rig in your editor, with
riffer acp
- Extensions — your own tools, commands and hooks
Contributing
AGENTS.md has the scripts and the project's conventions. Please follow the Code of Conduct.
License
MIT — see LICENSE.txt. Maintained by Jake Bottrall.
