Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/snarktank/ralph/llms.txt

Use this file to discover all available pages before exploring further.

While Ralph runs autonomously, you can monitor progress through several key files and commands.

​
Quick Status Check

Use jq to see which stories are complete: 
cat prd.json | jq '.userStories[] | {id, title, passes}'
Output: 
{
  "id": "US-001",
  "title": "Add priority field to database",
  "passes": true
}
{
  "id": "US-002",
  "title": "Display priority indicator on task cards",
  "passes": true
}
{
  "id": "US-003",
  "title": "Add priority selector to task edit",
  "passes": false
}
{
  "id": "US-004",
  "title": "Filter tasks by priority",
  "passes": false
}
Stories with "passes": true are complete. Stories with "passes": false are pending.

​
Understanding prd.json

The prd.json file is Ralph’s source of truth for what needs to be done.

​
Structure

{
  "project": "MyApp",
  "branchName": "ralph/task-priority",
  "description": "Task Priority System - Add priority levels to tasks",
  "userStories": [
    {
      "id": "US-001",
      "title": "Add priority field to database",
      "description": "As a developer, I need to store task priority so it persists across sessions.",
      "acceptanceCriteria": [
        "Add priority column to tasks table: 'high' | 'medium' | 'low' (default 'medium')",
        "Generate and run migration successfully",
        "Typecheck passes"
      ],
      "priority": 1,
      "passes": false,
      "notes": ""
    }
  ]
}

​
Key Fields

FieldPurpose
branchNameFeature branch Ralph creates/uses
priorityExecution order (1 = first)
passesfalse = pending, true = complete
notesOptional notes added during execution

​
Checking Completion Percentage

# Count total stories
total=$(cat prd.json | jq '.userStories | length')

# Count completed stories
completed=$(cat prd.json | jq '[.userStories[] | select(.passes == true)] | length')

echo "Progress: $completed/$total stories complete"

​
Reading progress.txt

The progress.txt file contains learnings and context from each iteration.

​
Structure

# Ralph Progress Log
Started: Wed Mar 11 2026
---

## Codebase Patterns
- Use `sql<number>` template for aggregations
- Always use `IF NOT EXISTS` for migrations
- Export types from actions.ts for UI components

---

## 2026-03-11 10:23 - US-001
Thread: https://ampcode.com/threads/abc123
- Added priority column to tasks table
- Created migration file: 20260311_add_priority.sql
- **Learnings for future iterations:**
  - The tasks table uses snake_case for column names
  - Migrations are in db/migrations/ directory
  - Run migrations with `npm run db:migrate`
---

## 2026-03-11 10:35 - US-002
Thread: https://ampcode.com/threads/def456
- Added PriorityBadge component to TaskCard
- Updated TaskCard.tsx to display priority
- **Learnings for future iterations:**
  - Badge component is in components/ui/badge.tsx
  - TaskCard uses Tailwind for styling
  - Color variants: red-500 (high), yellow-500 (medium), gray-400 (low)
---

​
Key Sections

1

Codebase Patterns (Top of File)

Consolidated learnings that apply across the entire codebase. Ralph checks this section first before starting work.
## Codebase Patterns
- Use `sql<number>` template for aggregations
- Always use `IF NOT EXISTS` for migrations
2

Iteration Entries (Chronological)

Each iteration appends a new entry with:
  • Date/time and story ID
  • Thread URL (for referencing previous work)
  • What was implemented
  • Files changed
  • Learnings for future iterations

​
Viewing Recent Progress

# View entire progress file
cat progress.txt

# View last 30 lines
tail -30 progress.txt

# Search for specific story
grep -A 10 "US-003" progress.txt

​
Thread URLs

Each progress entry includes a thread URL: 
Thread: https://ampcode.com/threads/$AMP_CURRENT_THREAD_ID
Future iterations can reference previous work using the read_thread tool if needed.

​
Checking Git History

Ralph commits after each successful iteration.

​
View Recent Commits

# Last 10 commits with one-line summary
git log --oneline -10
Output: 
abc123 feat: US-004 - Filter tasks by priority
def456 feat: US-003 - Add priority selector to task edit
ghi789 feat: US-002 - Display priority indicator on task cards
jkl012 feat: US-001 - Add priority field to database
mno345 Initial commit

​
View Full Commit Details

# See what changed in last commit
git show HEAD

# See what changed in specific story
git show --stat $(git log --oneline | grep "US-003" | cut -d' ' -f1)

​
Check Current Branch

git branch --show-current
Should match the branchName from prd.json (e.g., ralph/task-priority).

​
Monitoring Live Execution

While Ralph is running, you can monitor in real-time:

​
Watch Terminal Output

Ralph streams output from Amp/Claude Code to the terminal: 
===============================================================
  Ralph Iteration 3 of 10 (amp)
===============================================================
[Amp is implementing US-003...]
[Running typecheck...]
[Typecheck passed]
[Verifying in browser...]
[Browser verification passed]
[Committing changes...]
[Updating prd.json...]
Iteration 3 complete. Continuing...

​
Tail progress.txt in Another Terminal

tail -f scripts/ralph/progress.txt
Shows new entries as they’re appended.

​
Watch prd.json Updates

watch -n 5 'cat prd.json | jq ".userStories[] | {id, title, passes}"'
Refreshes every 5 seconds to show updated passes status.

​
Debugging Failed Iterations

If Ralph gets stuck or fails:
1

Check Which Story Failed

cat prd.json | jq '.userStories[] | select(.passes == false) | {id, title}' | head -1
Shows the first incomplete story (likely the one that failed).
2

Review Terminal Output

Scroll up in the terminal to see error messages from the failed iteration.
3

Check progress.txt

tail -50 progress.txt
See what the last iteration learned and what might have caused the failure.
4

Inspect Git Status

git status
Check for uncommitted changes or merge conflicts.
5

Review Acceptance Criteria

cat prd.json | jq '.userStories[] | select(.id == "US-XXX")'
Verify the story’s acceptance criteria are achievable.

​
Quality Check Status

Ralph runs quality checks before committing. Monitor these:

​
Typecheck Status

# Run typecheck manually
npm run typecheck
# or
tsc --noEmit

​
Test Status

# Run tests manually
npm test
# or
npm run test:unit

​
Lint Status

# Run linter manually
npm run lint
If any quality check fails, Ralph will NOT commit. The iteration will retry or move to the next story.

​
AGENTS.md Updates

Ralph updates AGENTS.md files with discovered patterns. Check these for valuable learnings: 
# Find all AGENTS.md files
find . -name "AGENTS.md" -type f

# View a specific AGENTS.md
cat src/components/AGENTS.md

​
What to Look For

Valuable Learnings

  • Patterns: “This module uses pattern X for all API calls”
  • Gotchas: “When modifying Y, also update Z to keep them in sync”
  • Dependencies: “Component A requires B to be imported first”
  • Testing: “Tests require the dev server running on PORT 3000”

​
Archive Directory

When starting a new feature, Ralph archives previous runs: 
ls -la scripts/ralph/archive/
Output: 
drwxr-xr-x  3 user  staff   96 Mar 10 15:23 2026-03-10-old-feature
drwxr-xr-x  3 user  staff   96 Mar 09 14:12 2026-03-09-another-feature
Each archive contains:
  • prd.json - The completed task list
  • progress.txt - All learnings from that run

​
Reviewing Past Features

# See what stories were in a previous feature
cat scripts/ralph/archive/2026-03-10-old-feature/prd.json | jq '.userStories[] | {id, title, passes}'

# Read learnings from previous run
cat scripts/ralph/archive/2026-03-10-old-feature/progress.txt

​
Completion Signal

When all stories are complete, Ralph outputs: 
<promise>COMPLETE</promise>

Ralph completed all tasks!
Completed at iteration 4 of 10
And exits with code 0.

​
Verify Completion

# All stories should show passes: true
cat prd.json | jq '.userStories[] | .passes' | sort -u
Output: 
true
If you only see true, all stories are complete.

​
Summary Commands

Here’s a quick reference for monitoring: 
# Check story completion status
cat prd.json | jq '.userStories[] | {id, title, passes}'

# Count completed vs total
total=$(cat prd.json | jq '.userStories | length')
completed=$(cat prd.json | jq '[.userStories[] | select(.passes == true)] | length')
echo "Progress: $completed/$total"

# View recent progress entries
tail -30 progress.txt

# View recent commits
git log --oneline -10

# Check current branch
git branch --show-current

# Watch for updates (in another terminal)
watch -n 5 'cat prd.json | jq ".userStories[] | {id, passes}"'

​
Next Steps

Once Ralph completes all stories:
  1. Review commits - Check git log for all changes
  2. Run tests manually - Verify everything works
  3. Test in browser - Manually verify UI changes
  4. Create pull request - Merge the feature branch
  5. Archive or clean up - Ralph already archived previous runs

Autonomous Completion

When monitoring shows all stories with passes: true, your feature is ready for review!

Build docs developers (and LLMs) love

Get started for freeTalk to us