Monitoring Progress

Check Ralph’s status via prd.json, progress.txt, and git log to track autonomous execution

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

Field	Purpose
branchName	Feature branch Ralph creates/uses
priority	Execution order (1 = first)
passes	false = pending, true = complete
notes	Optional 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!