Ralph It

ralph-it Skill

Autonomous agent loop runner powered by GitHub Issues. Zero dependencies, built with Bun.

See references/ for detailed documentation on each topic.

Quick Start

# In your project directory:
ralph-it init              # Create RALPH.md + .ralph/
ralph-it setup             # Create 19 labels on GitHub
ralph-it doctor            # Verify everything works
ralph-it run --watch       # Start autonomous loop

Quick Decision Trees

"I need to set up ralph-it on a project"

Setup ralph-it?
├─ Fresh project → ralph-it init, then ralph-it setup, then ralph-it doctor
├─ Existing project → Same flow, edit RALPH.md to match your project
├─ CI/CD only → See references/github-actions.md
└─ Different agent (not Claude) → See references/agents.md for config

After setup, create issues and label them ralph:queued. See references/issues.md for the standard format.

"I need to create issues for ralph-it"

Create issues?
├─ Single task → Use the standard issue template (see below)
├─ Batch from TODOs → Search codebase for TODO/FIXME, create one issue per item
├─ From backlog → Add ralph:queued label to existing issues
└─ Sub-tasks → Create separate issues, use priority labels to order them

CRITICAL: Issue format matters. Structured issues give the agent clear context. Always use the standard format — see references/issues.md.

"I need to write or edit RALPH.md"

RALPH.md?
├─ New project → ralph-it init gives you a template, customize it
├─ Add commands → command.name = ./script.sh (with optional timeout)
├─ Change agent → agent.command, agent.args, agent.input
├─ Add context → Use {{ }} placeholders for repo, issue, commands, args
├─ Private notes → Use <!-- HTML comments --> (stripped from prompt)
└─ Full syntax → See references/ralph-md.md

"I need to run or monitor a loop"

Run loop?
├─ Process all queued → ralph-it run
├─ Single issue → ralph-it run --issue 42
├─ Watch mode → ralph-it run --watch --interval 30
├─ Filter issues → ralph-it run --label type:bug --milestone v2
├─ Monitor live → tail -f .ralph/logs/*.jsonl
├─ Check status → ralph-it status
├─ See queue → ralph-it list
└─ Troubleshoot → ralph-it doctor

Standard Issue Format

When creating issues for ralph-it, ALWAYS use this format:

## Context
Brief background — what exists now, what's the problem or need.

## Task
Precise description of what the agent should do. Be specific.

## Acceptance Criteria
- [ ] Tests pass
- [ ] No new lint errors
- [ ] [Task-specific criteria]

## Scope
Files and modules the agent should focus on.
- `src/auth/` — authentication module
- `src/api/routes.ts` — API routes

## Constraints
What the agent should NOT do.
- Do not modify the database schema
- Do not change public API signatures

Required labels: Always add ralph:queued + one type: label + one priority: label.

Why this format: Each section maps to what the agent needs:

• Context → understands the "why"
• Task → knows exactly what to do
• Acceptance Criteria → knows when it's done
• Scope → stays focused, doesn't wander
• Constraints → avoids breaking things

Label System Overview

Full details: references/labels.md

RALPH.md Frontmatter Quick Ref

---
agent.command = claude
agent.args = -p --dangerously-skip-permissions
agent.input = stdin
agent.timeout = 600
credit = true
command.coverage = ./check-coverage.sh
command.coverage.timeout = 120
command.lint = npm run lint
---

Template Placeholders

Multi-LLM Quick Config

Full agent configuration guide: references/agents.md

Reference Index