Riff

A lightweight daemon that coordinates AI agents around human-defined tasks.

Quick Start

pnpm install && pnpm build
pnpm link --global             # puts `riff` on PATH

cd your-repo
riff init                      # scaffold riff.yaml
riff setup                     # register the MCP server with Claude Code / Codex / Copilot
riff start -d                  # run the daemon in the background
riff add "fix login bug" -p 1  # create a task
riff board                     # kanban view
riff tui                       # live cockpit (read-only)
riff stop                      # when you're done

Architecture

 Upstream Sources               Riff Daemon              Downstream Agents
 ──────────────────     ────────────────────────────     ──────────────────────────
                        ┌──────────────────────────┐
  CLI (riff add) ───────┤                          ├──  Claude Code (MCP stdio)
                        │   SQLite   ←→  Services  │
  REST / Webhooks ──────┤                          ├──  Cursor / Agents (REST)
                        │   EventBus ←→  Hono API  │
  riff.yaml ────────────┤                          ├──  CI / Scripts (REST)
                        └──────────────────────────┘

Tasks flow in from the left (CLI, REST API, webhook, or YAML manifest), are stored in SQLite, and are consumed by agents on the right via MCP tools or REST endpoints. The daemon is the single source of truth.

Core Concepts

Task

Field	Description
id	Auto-generated ULID (task_...)
project_id	Project the task belongs to
initiative	Free-form tag grouping related work across projects (optional)
title	Short description of the work
status	Current lifecycle status
priority	0 (critical) to 3 (low), default 2
dependencies	List of task IDs that must be done before this task can be claimed
claimed_by	Agent ID holding the task
result	Work product (diff, pr_url, file, or text)

Status Lifecycle

available ──→ claimed ──→ working ──→ review ──→ done
    ↑            │           │          │
    └────────────┴───────────┴──────────┘
                                        │
                 failed ←───────────────┘
                   │
                   └──→ available (retry)

• available — ready to be claimed
• claimed — locked by an agent
• working — agent is actively working
• review — result submitted, awaiting human approval
• done — approved and complete
• failed — can be retried (transitions back to available)

Agent

Agents register with an agent_id, optional runtime label, capabilities list, and scope. When disconnected, their in-progress tasks are released back to available.

Docs

• CLI reference — every command, options, examples
• riff.yaml manifest — repo binding, task import, initiatives
• REST API — endpoints, SSE, event envelope
• MCP server — tools, Claude Code integration
• Webhook bridge — remote access, API keys, config
• Example manifests

License

MIT