Ralph

Autonomous agent loop for Claude Code. Decomposes a spec into tasks, executes them one per iteration with crash recovery and handoff context.

Inspired by snarktank/ralph, rebuilt from scratch with filesystem-based state, bash task management, and agent-controlled exit signals.

What's in the box

.project/
  PROMPT.md          # Agent instructions (the system prompt for each iteration)
  SPEC.md            # Your project spec (replace with your own)
  task               # Bash task runner — manages task state via the filesystem
  loop               # Python loop runner — calls `claude --print` in a loop
  tasks/             # Task files live here (one .md per task)
    FS-001.md        # Example tasks from a sample "filestats" spec
    FS-002.md
    FS-003.md
    FS-004.md

.claude/
  commands/
    spec-to-tasks.md # Claude Code custom command: /spec-to-tasks

How it works

1. Write a spec

Replace .project/SPEC.md with your own project description. Keep it concrete — what to build, what technologies, what's in/out of scope.

2. Generate tasks

Run the custom command inside Claude Code:

/spec-to-tasks

This reads your spec and decomposes it into individual task files in .project/tasks/, each with frontmatter (id, priority, complexity, dependencies) and acceptance criteria.

3. Run the loop

python3 .project/loop

Each iteration, the agent:

1. Reads HANDOFF.md (or SPEC.md on first run) for context
2. Picks the next task (respecting priority and dependencies)
3. Implements it, runs quality checks
4. Commits, writes a handoff for the next iteration
5. Writes a STOP file when all tasks are done (or if blocked/needs clarification)

Options:

--max N        Max iterations (default: 50)
--delay N      Seconds between iterations (default: 3)
--model NAME   Model override (e.g. claude-sonnet-4-20250514)
--verbose      Show assistant text as it streams

Logs go to .project/logs/ (raw JSONL + human-readable summaries per iteration).

4. Or run tasks manually

You don't have to use the loop. The task runner works standalone:

.project/task next            # Next available task (priority + deps)
.project/task list            # All tasks by status
.project/task FS-001          # View task details
.project/task FS-001 progress # Mark in-progress
.project/task FS-001 done     # Mark complete (moves to tasks/done/)

Task file format

---
id: PREFIX-NNN
priority: N
complexity: s|m|l
depends: [PREFIX-001, PREFIX-002]
---
# Task title

Description with enough context for a fresh agent.

## Acceptance Criteria

- [ ] Specific, verifiable criterion
- [ ] Another criterion

State is managed by the filesystem: FOO-001.md = open, FOO-001.progress.md = in-progress, done/FOO-001.md = completed.

Key design decisions

• No database, no server. State lives in markdown files and filenames. You can inspect and edit everything with a text editor.
• One task per iteration. The agent does one thing, commits, and hands off context via HANDOFF.md. This keeps each context window focused and makes progress visible.
• Crash recovery. If an iteration dies mid-task, the .progress.md file remains. The next iteration picks it back up automatically.
• Exit signals. The agent writes a .project/STOP file to communicate completion (DONE:), blockers (BLOCKED:), or questions (CLARIFY:). The loop reads this and exits with the appropriate code.

Prerequisites

• Claude Code CLI installed and on your PATH
• Python 3.11+ (for the loop runner)
• Git (the agent commits after each task)

Adapting for your project

1. Copy this scaffold into your repo
2. Replace .project/SPEC.md with your spec
3. Delete the example FS-*.md task files
4. Run /spec-to-tasks in Claude Code to generate your tasks
5. Run python3 .project/loop and watch it go