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 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.