Your First Task

Let's walk through creating and running a complete task with Ralph.

Choose Your Mode

Ralph offers two modes. Choose based on your task complexity:

For this guide, we'll use traditional mode first, then show hat-based mode.

Traditional Mode Example

1. Initialize

mkdir my-first-ralph-task
cd my-first-ralph-task
git init  # Ralph works best with git

ralph init --backend claude

2. Create Your Prompt

Create PROMPT.md:

# Task: Build a Simple Calculator (Rust)

Create a Rust calculator module with:

## Requirements
- Functions: add, subtract, multiply, divide
- Handle division by zero gracefully
- Include unit tests

## Acceptance Criteria
- All functions work correctly
- Tests pass with `cargo test`
- Code is formatted with `cargo fmt`

3. Run Ralph

ralph run

Ralph will:

1. Read your prompt
2. Start the AI agent
3. Iterate until LOOP_COMPLETE is output
4. Show progress in the TUI

4. Review Results

When Ralph completes, check your directory:

ls -la
# src/lib.rs
# tests/calculator.rs
# etc.

# Run the tests
cargo test

Hat-Based Mode Example

For more complex tasks, use hats to separate concerns.

1. Initialize Core Config

ralph init --backend claude

Then run with a specialized hat collection (recommended: code-assist):

ralph run -c ralph.yml -H builtin:code-assist

This uses specialized hats:

• Tester - Writes failing tests first
• Implementer - Makes tests pass
• Refactorer - Cleans up the code

2. Create Your Prompt

# Task: Build a URL Shortener

Create a URL shortening service with:

## Requirements
- Generate short codes for URLs
- Retrieve original URLs from short codes
- Handle invalid inputs gracefully
- Persist mappings to SQLite

## Constraints
- Short codes: 6 alphanumeric characters
- No duplicate short codes

3. Run with Hat Coordination

ralph run

The TUI shows which hat is active:

[iter 3] 00:02:15 Tester

4. View Event History

ralph events

Shows the event flow between hats:

task.start -> Tester
test.written -> Implementer
test.passed -> Refactorer
refactor.done -> Tester
...

Tips for Good Prompts

Be Specific

# Bad
Make a web app.

# Good
Create an Axum web app with:
- GET /health endpoint returning {"status": "ok"}
- POST /users accepting JSON {name, email}
- SQLite database for persistence

Include Acceptance Criteria

## Acceptance Criteria
- [ ] All endpoints respond correctly
- [ ] Invalid JSON returns 400 error
- [ ] Database persists across restarts

Specify Constraints

## Constraints
- Use Axum (not Actix)
- Rust 1.75+
- No external API calls

Monitoring and Control

View Progress

The TUI shows real-time progress. Key information:

• Iteration count - How many cycles Ralph has run
• Elapsed time - Total runtime
• Active hat - Which persona is working (hat-based mode)
• Agent output - What the AI is doing

Stop Early

Press q in the TUI to quit gracefully.

Resume Interrupted Sessions

ralph run --continue

Check Metrics

After completion, check .agent/ for:

• scratchpad.md - Iteration state (per-hat scratchpads may also exist)
• memories.md - Persistent learning
• tasks.jsonl - Task tracking

Common Issues

Task Not Completing

If Ralph runs forever:

1. Check your prompt has clear completion criteria
2. Ensure LOOP_COMPLETE can be reasonably output
3. Set a lower --max-iterations for testing

Wrong Backend

# Explicitly specify backend
ralph run --backend kiro

Agent Errors

Check the agent is installed and authenticated:

# Test Claude directly
claude -p "Hello"

# Test Kiro
kiro -p "Hello"

Next Steps

• Learn about Hats & Events
• Explore Presets for your workflow
• Master Writing Prompts