ravn

AI agent distribution framework for Linear + GitHub.

ravn distributes work to AI agents via Linear tickets. Drop it into any repository as a single compiled binary — no hardcoded workspace or repo assumptions.

Requirements

Set these environment variables before running ravn setup:

Variable	Required	Description
LINEAR_API_KEY	Yes	Linear API key (Settings → API → Personal API keys)
GITHUB_TOKEN	Yes	GitHub personal access token with repo scope

The webhook signing secret (LINEAR_WEBHOOK_SECRET) is printed during setup. Set it before starting the webhook listener, or let ravn webhook fetch it automatically from Linear on startup.

Installation

go install github.com/nnunodev/ravn

Setup

Run once in your project root:

ravn setup

Setup resolves your GitHub repo from the local git remote, then prompts for your Linear team, project, and webhook URL. It creates:

• Agent and priority labels in Linear
• A PR Open workflow state
• A webhook subscription for your public URL
• .agent/config.yml with all resolved IDs

Add .agent/ to .gitignore — the config contains workspace-specific IDs and should not be committed.

Workflow

Tickets flow through states:

Todo → In Progress → In Review → PR Open → Done

• Todo: Ready to be picked up
• In Progress: An agent is working on it
• In Review: Awaiting reviewer verification
• PR Open: PR opened, awaiting merge
• Done: Merged and complete

Move a ticket to In Progress in Linear — the webhook picks it up and dispatches the right agent automatically.

Agent Types

Agent	Description
coder	Implements features and fixes
tester	Writes and runs tests
reviewer	Reviews work against acceptance criteria
researcher	Gathers context from the codebase
writer	Writes documentation and content

Commands

setup

Initialize a repository for ravn. Resolves team, project, and webhook URL interactively.

ravn setup
ravn setup --repo owner/repo --team TEAM_ID
ravn setup --webhook-url https://example.ngrok.app/ravn/webhook --force

webhook

Start the Linear webhook listener. Requires LINEAR_WEBHOOK_SECRET or fetches it from Linear automatically.

ravn webhook
ravn webhook --port 8765
ravn webhook --allow-insecure  # disable HMAC verification, local dev only

• GET /health returns {"status":"ok","pid":<pid>}
• GET /metrics returns counters for webhook events and agent runs

create

Derive and create tickets from AGENTS.md using AI.

ravn create
ravn create "add password reset flow"
ravn create --dry-run
ravn create --simple --title "Fix login bug" --agent coder --criteria "login works"

run

Claim and execute a specific ticket.

ravn run coder --issue-id PROJ-123
ravn run reviewer --issue-id PROJ-123
ravn run coder --issue-id PROJ-123 --dry-run

review

Review a completed ticket and post a verdict (manual command).

ravn review 42
ravn review 42 --include-diff

Requires OPENROUTER_API_KEY when execution_mode is api.

status

Show the current state of a Linear ticket.

ravn status PROJ-123

stale

Find and recover tickets stuck in progress.

ravn stale
ravn stale --dry-run

cleanup

Cancel active Linear issues and remove local ravn files.

ravn cleanup
ravn cleanup --force

test

Run a full test cycle: cleanup, setup, and create a ticket.

ravn test "Write a hello world CLI tool"
ravn test --force "Add user authentication"

build

Build and install ravn from source.

ravn build
ravn build --version v1.0.0

admin

Inspect configuration, check connectivity, and query Linear issues.

ravn admin preflight                          # check env vars and API connectivity
ravn admin show-config                        # display current configuration
ravn admin list-issues --state "In Progress"  # list issues by state

Global Flags

Flag	Description
--config	Config file path (default: .agent/config.yml)
--version	Print version information

Configuration

ravn setup writes .agent/config.yml automatically. See .agent/config.example.yml for all available fields and their defaults.

Optional Environment Variables

These override or supplement config file values:

Variable	Description
LINEAR_WEBHOOK_SECRET	Webhook HMAC secret — auto-fetched from Linear if unset
OPENROUTER_API_KEY	Required for ravn review in api execution mode
ZAI_MODEL_DERIVE	Override the model used for ticket derivation
ZAI_MODEL_FALLBACK	Fallback model for agent execution
ZAI_MODEL_<TYPE>	Per-agent model override (e.g. ZAI_MODEL_CODER)
RAVN_ALERT_WEBHOOK_URL	Discord webhook URL for circuit-breaker and agent failure alerts
RAVN_ALERT_ENABLED	Set to false to disable alerting (enabled by default when URL is set)

License

MIT