microralph

Pronunciation: Some say it's pronounced "mister" (μr → Mr.). We neither confirm nor deny this.

A small ralph so you can ralph your ralphs. 🦙

microralph is a tiny CLI that wraps your favorite AI coding agent (including GitHub Copilot CLI and Claude Code CLI) and turns it into a PRD-driven task loop. You write PRDs (Product Requirements Documents), and microralph repeatedly invokes the agent—one task at a time—until everything is done.

Oh, and yes: microralph was entirely ralph'd into existence by microralph itself. Dogfooding at its finest. 🐕

What is a Ralph?

A project that is mostly ralph'd into existence by AI agents is itself called a ralph (by me). I'm hoping one day it becomes a verb so people can say things like, "I ralphed it." microralph is a ralph—it was built almost entirely by running mr run in a loop, with a human steering via PRDs.

The name comes from Ralph Wiggum: loveable, earnest, occasionally brilliant, but needs guidance. AI agents are the same way.

The Real Value: Locking Time for Artisanal Code

Here's the thing: you don't want to ralph everything. Some code deserves your full attention—the elegant algorithm, the nuanced architecture, the domain-specific logic that only you understand. That's artisanal code.

But most projects need a lot of other code: CLI scaffolding, config parsing, test harnesses, CI pipelines, documentation. Important, but not where you want to spend your creative energy.

microralph lets you ralph the boring parts so you can lock time for the good stuff.

Use it to:

Build internal tools and utilities you need but don't want to hand-craft
Scaffold new projects with all the boilerplate handled
Implement features that are well-defined but tedious
Free up your time for higher-value work

The goal isn't to replace you—it's to give you time back.

Why microralph?

AI coding agents are powerful, but they have a fatal flaw: context windows. The more context an agent accumulates, the slower and more expensive it gets—and eventually it forgets what it was doing.

microralph solves this by:

Breaking work into discrete tasks via PRDs
Running one task per invocation so context never bloats
Persisting state in git-tracked Markdown so the agent can pick up where it left off
Logging History so failed attempts inform future runs

No more 200k-token conversations that go off the rails. Just focused, atomic task execution.

The Normal Flow

┌─────────────────────────────────────────────────────────────┐
│  1. mr init / mr bootstrap     ← Set up .mr/ structure     │
│  2. mr new my-feature          ← Create PRD via guided Q/A │
│  3. mr run                     ← Execute one task          │
│  4. Agent implements, runs UAT, updates PRD, commits       │
│  5. Repeat step 3 until all tasks are done                 │
└─────────────────────────────────────────────────────────────┘

Each mr run invocation:

Picks the highest-priority incomplete task
Invokes the underlying agent with a focused prompt
Expects the agent to: implement, verify with UAT, update PRD status/history, commit
Exits—keeping context minimal for the next run

Features

PRD-driven development: Structure your work as markdown PRDs with YAML frontmatter
One-task-per-run loop: Context stays small, agents stay focused
Guided PRD creation: mr new runs an interactive Q/A to generate PRDs
Bootstrap existing repos: mr bootstrap scans your repo and generates starter PRDs
Constitution-based governance: Define project rules in .mr/constitution.md to guide PRD workflows
Multi-language support: Works with Rust, Python, Node.js, Go, Java (auto-detected)
Streaming output: mr run --stream shows agent output in real-time
Git-native state: PRDs are versioned markdown; no databases or JSON blobs
Runner abstraction: Pluggable adapters (Copilot, mock for testing, more to come)

Installation

Pre-built Binaries (Recommended)

Download pre-built binaries from GitHub Releases. Available for:

Linux x86_64 (mr_x86_64-unknown-linux-gnu)
macOS ARM (mr_aarch64-apple-darwin)
Windows x86_64 (mr_x86_64-pc-windows-gnu.exe)
WASM32-WASIP2 (mr_wasm32-wasip2.wasm)

Linux

$ curl -L https://github.com/twitchax/microralph/releases/latest/download/mr_x86_64-unknown-linux-gnu -o /usr/local/bin/mr
$ chmod a+x /usr/local/bin/mr

Mac OS (Apple Silicon)

$ curl -L https://github.com/twitchax/microralph/releases/latest/download/mr_aarch64-apple-darwin -o /usr/local/bin/mr
$ chmod a+x /usr/local/bin/mr

Windows

$ iwr https://github.com/twitchax/microralph/releases/latest/download/mr_x86_64-pc-windows-gnu.exe -OutFile C:\Users\$env:USERNAME\AppData\Local\Programs\mr\mr.exe

Cargo

$ cargo install microralph

WebAssembly (via OCI Registry)

The WASM binary is published to GitHub Container Registry. Download and run with any WASI-compatible runtime. This works well for sandboxed or cross-platform use cases.

# Download from OCI registry using wkg (WebAssembly Package Manager)
cargo binstall wkg --no-confirm
wkg oci pull ghcr.io/twitchax/microralph:latest -o mr.wasm

# Run with wasmtime
wasmtime mr.wasm -h

# Optional: Create an alias
echo 'alias mr="wasmtime /path/to/mr.wasm"' >> ~/.bashrc

Or download from GitHub Releases:

# Download the WASM binary
curl -L https://github.com/twitchax/microralph/releases/latest/download/mr.wasm -o mr.wasm

# Run with wasmtime
wasmtime mr.wasm -h

From Source

git clone https://github.com/twitchax/microralph.git
cd microralph
cargo install --path .

Usage

# Initialize a new repo with .mr/ structure
mr init

# Bootstrap an existing repo into PRDs
mr bootstrap

# Get AI-generated PRD suggestions
mr suggest

# Create a new PRD via guided Q/A
mr new my-feature

# List all PRDs
mr list

# Run the next task from the active PRD
mr run

# Show status of PRDs and tasks
mr status

Commands

Command	Description
`mr init`	Initialize a new repo with `.mr/` structure, templates, prompts, and starter AGENTS.md
`mr init --language <lang>`	Initialize for a specific language (rust, python, node, go, java)
`mr bootstrap`	Ingest an existing repo into PRDs: generate `.mr/PRDS.md` and starter PRDs
`mr restore`	Restore `.mr/prompts/` and `.mr/templates/` to built-in defaults (destructive)
`mr suggest`	Generate 5 AI-powered PRD suggestions based on codebase analysis and research
`mr new <slug>`	Create a new PRD via guided Q/A
`mr new <slug> --context`	Create a new PRD with upfront context to guide initial questions
`mr edit <id> "<request>"`	Edit an existing PRD via runner assistance
`mr constitution edit "<request>"`	Edit the constitution via LLM assistance
`mr list`	List all PRDs (regenerates `.mr/PRDS.md`)
`mr finalize <id>`	Finalize a PRD (mark as done and close out)
`mr run`	Run the next task from the highest-priority active PRD
`mr run <id>`	Run the next task from a specific PRD
`mr run --stream`	Run with real-time streaming output
`mr run --no-commit`	Run without instructing the agent to commit (for manual review)
`mr refactor`	Run iterative AI-driven code improvements (default 3 iterations)
`mr refactor --context "<hint>"`	Focus refactors on a specific improvement area
`mr refactor --path <dir>`	Constrain refactors to a specific directory/file pattern
`mr refactor --dry-run`	Preview refactor suggestions without applying changes
`mr reindex`	Regenerate index and verify/fix PRD interlinks
`mr status`	Show status of PRDs and tasks

Flags

Flag	Description
`-v, --verbose`	Enable verbose output
`-q, --quiet`	Suppress non-essential output
`--runner <runner>`	Specify runner: `copilot`, `claude`, `mock` (default: `copilot`)
`--model <model>`	Specify model (passed through to runner)
`--stream`	Stream runner output in real-time (for `mr run`)

Configuration

Settings can be persisted in .mr/config.toml:

runner = "copilot"
model = "claude-sonnet-4.5"
permission_mode = "yolo"
timeout_minutes = 30
no_commit = false           # Set to true to prevent commit instructions in prompts

CLI flags override config file settings (e.g., --no-commit overrides no_commit).

Dev Containers

microralph supports dev containers for consistent, sandboxed development environments. Dev containers isolate your development environment from your host machine, ensuring all tools and dependencies are versioned and reproducible.

Why Use Dev Containers?

Consistency: Every developer works in the same environment
Isolation: Protects your host machine from experimental or potentially risky operations
Reproducibility: Codify all dependencies and tools in version control
Onboarding: New contributors can get started in seconds
Safety: Run AI-generated code in a sandbox without risk to your local machine

Supported Workflows

microralph dev containers work with:

VSCode: Install the Dev Containers extension and open the repo—VSCode will prompt you to reopen in a container
GitHub Codespaces: Open the repo in Codespaces for a fully cloud-based dev environment

CLI: Use the Dev Container CLI to build and run containers from the terminal:

# Install the CLI
npm install -g @devcontainers/cli

# Open a shell in the dev container
devcontainer up --workspace-folder .
devcontainer exec --workspace-folder . bash

Generating Dev Container Configs

microralph can automatically generate .devcontainer/devcontainer.json by analyzing your repository:

mr devcontainer generate

This command:

Scans your repository structure (languages, frameworks, dependencies)
Analyzes git history for recently added tools
Reads PRDs for tool references
Generates a .devcontainer/devcontainer.json with appropriate base image, extensions, and tool installations

The generated config includes:

Base container image matching your primary language
Pre-installed development tools (cargo-make, cargo-nextest, etc.)
VSCode extensions relevant to your stack
Forwarded ports for local services
Initialization scripts to set up the environment

Dev Container Warnings

When running commands that invoke AI models (mr run, mr new, mr devcontainer generate), microralph will show a brief warning if you're not inside a dev container. This is informational only—commands will still execute normally.

To suppress the warning, either:

Work inside a dev container (recommended)
Run commands in an environment where dev container detection identifies container usage

Regenerating After Changes

As your project evolves, regenerate the dev container config to keep it in sync:

# Analyze current state and update .devcontainer/devcontainer.json
mr devcontainer generate

This is especially useful after:

Adding new dependencies or tools
Switching to a different language or framework
Major architectural changes documented in PRDs

Restoring Prompts and Templates

The mr restore command overwrites .mr/prompts/ and .mr/templates/ with built-in defaults. This is useful when you want to:

Reset customizations: Revert custom prompts/templates back to microralph's defaults
Update to latest built-ins: Pull in updated prompts/templates after upgrading microralph
Compare customizations: Use Git diff to review your changes against the latest defaults

How It Works

mr restore

The command:

Deletes .mr/prompts/ and .mr/templates/ directories
Recreates them with built-in defaults (same logic as mr init)
Leaves changes uncommitted so you can review via Git

Reviewing Changes

After running mr restore, use Git to see what changed:

# See all changes
git diff

# Review specific file
git diff .mr/prompts/run_task.md

# Decide whether to keep or discard
git add .mr/            # Keep the restored defaults
git restore .mr/        # Discard and keep your customizations

Important Notes

Destructive operation: This overwrites customizations with no backup
No auto-commit: Changes remain uncommitted for your review
Git is your safety net: Committed customizations can always be recovered via git log and git checkout
Scope: Only affects .mr/prompts/ and .mr/templates/ (not .mr/constitution.md or .mr/config.toml)

Use Cases

Scenario 1: You customized prompts but want to start fresh

mr restore
git diff             # Review what changed
git add .mr/         # Commit to accept defaults

Scenario 2: You upgraded microralph and want new prompt features

mr restore
git diff             # See new features in built-in prompts
git add .mr/prompts/ # Keep new prompts
git restore .mr/templates/  # Keep your template customizations

Scenario 3: You're curious what's different between your customizations and defaults

mr restore
git diff             # Review differences
git restore .mr/     # Discard restore and keep customizations

Constitution

microralph supports project-specific governance rules via a Constitution file (.mr/constitution.md). The constitution defines constraints, best practices, and architectural rules that influence PRD creation and execution.

What's the Constitution For?

The constitution provides a single source of truth for project governance:

Define acceptance test requirements (e.g., "All UATs must be codified in Makefile.toml")
Enforce architectural patterns (e.g., "Use anyhow::Result for all fallible functions")
Set coding standards (e.g., "Avoid XML/JSON state blobs; use human-readable Markdown")
Document project-specific constraints

How It Works

Bootstrap creates it: When you run mr init or mr bootstrap, microralph creates .mr/constitution.md with commented-out example rules.
Version controlled: The constitution is committed to git alongside your PRDs.
Influences workflows: Commands like mr new and mr finalize read the constitution and pass it to the LLM, which respects the rules when creating or finalizing PRDs.
Intelligent editing: Use mr constitution edit "<request>" to update the constitution via natural language (e.g., "Add a rule that all tests must use nextest").
Violation logging: When executing tasks, the runner logs any constitution violations in the PRD History section with reasoning—but violations do not block execution.

Example Constitution

# Constitution

## Purpose
This file defines project-specific governance rules that guide PRD creation and execution.

## Rules

1. All acceptance tests must be codified in Makefile.toml (no one-off commands).
2. Use `anyhow::Result` for all fallible functions.
3. Prefer functional programming techniques where appropriate.
4. All dev commands must route through `cargo make`.

Editing the Constitution

You can edit .mr/constitution.md directly, or use the LLM-assisted command:

# Add a new rule via natural language
mr constitution edit "Add a rule requiring tracing instead of println for diagnostics"

# The LLM will ask clarifying questions and update the constitution

Enforcement Model

Constitution violations are informational, not blocking:

The runner mentions violations in PRD History entries with reasoning
Violations provide feedback but don't fail builds or prevent commits
This allows flexibility while maintaining visibility into governance compliance

User Flows

The Complete microralph Experience

Let's walk through every way you can use microralph, from "I just heard about this" to "I'm shipping features like a boss."

Starting Fresh: The New Project Flow

You've got a brilliant idea and zero code. Here's how microralph helps you ralph it into existence:

# 1. Initialize your project
mkdir my-awesome-project
cd my-awesome-project
git init
mr init                          # Creates .mr/ structure, templates, and AGENTS.md

# 2. (Optional) Specify a language if not Rust
mr init --language python        # or node, go, java

# 3. Create your first PRD
mr suggest                        # Get 5 AI-generated suggestions (pick one or ignore)
mr new add-cli-parser            # Guided Q/A creates .mr/prds/PRD-0001-add-cli-parser.md

# 4. Run the loop until it's done
mr run                           # Agent implements T-001, runs tests, commits
mr run                           # Agent implements T-002, runs tests, commits
mr run                           # ... repeat until all tasks done

# 5. Check progress anytime
mr status                        # Show what's done, what's left
mr list                          # Regenerate .mr/PRDS.md index

# 6. Finalize when complete
mr finalize PRD-0001             # Mark PRD as done, append summary

Pro tip: Let mr run loop until the PRD is finished. Each run does one task and exits—no context bloat, no forgotten instructions.

Adding to Existing: The Bootstrap Flow

You've got a mature codebase but want to ralph new features onto it:

# 1. Bootstrap existing repo
cd my-existing-project
mr bootstrap                     # Scans repo, creates .mr/, generates starter PRDs

# 2. Review what was generated
mr list                          # See auto-generated PRDs
cat .mr/PRDS.md                  # Human-readable index

# 3. Edit or create new PRDs
mr edit PRD-0001 "Split T-003 into two tasks"  # LLM helps you edit
mr new add-auth                  # Create new PRD for auth feature

# 4. Run tasks
mr run                           # Picks highest-priority task from active PRDs
mr run PRD-0002                  # Force run from specific PRD

# 5. Stream for long tasks (optional)
mr run --stream                  # Watch the agent work in real-time

Pro tip: Use mr suggest after bootstrapping to get fresh ideas based on your codebase—it's like pair programming with an overenthusiastic intern who actually reads your TODO comments.

Day-to-Day: The Task Loop Flow

You're in the flow. PRDs are planned, tasks are queued. Here's your daily routine:

# Morning: Check what's up
mr status                        # "3 active PRDs, 12 tasks remaining"

# Pick your battle
mr run PRD-0003                  # Work on specific PRD
mr run                           # Let microralph pick highest priority

# Agent does the work:
# - Reads PRD and task details
# - Implements changes
# - Runs `cargo make uat` (or equivalent)
# - Updates PRD status and History
# - Commits with standardized message

# Rinse and repeat
mr run && mr run && mr run       # Chain 'em if you're feeling spicy

# End of day: Survey the damage
mr status
git log --oneline -10            # See what the agent committed

Pro tip: Use mr run --stream when you're actively watching—you'll see the agent's thought process unfold in real-time. Use plain mr run when you're grabbing coffee.

Advanced: Constitution-Driven Development

You want to enforce project rules (e.g., "All tests must use nextest," "No XML config blobs"). Enter the Constitution:

# 1. Edit your constitution
vim .mr/constitution.md          # Or use the LLM assistant:
mr constitution edit "Add rule: all functions must have doc comments"

# 2. PRD creation respects the constitution
mr new add-logging               # Agent asks about tracing vs println because constitution says so

# 3. Task execution logs violations
mr run                           # If agent violates constitution, it notes it in History
                                 # (but doesn't block—violations are informational)

# 4. Check compliance
grep -r "Constitution" .mr/prds/ # See where violations were noted

Pro tip: The constitution is git-tracked, so it evolves with your project. Update it as you learn what patterns work.

Configuration: Making microralph Yours

Don't like the defaults? Tweak them:

# Global CLI flags (override everything)
mr run --runner copilot --model claude-sonnet-4.5 --stream

# Or use Claude Code CLI instead
mr run --runner claude --model claude-sonnet-4.5 --stream

# Persistent config (set once, forget)
cat > .mr/config.toml <<EOF
runner = "claude"                 # Use Claude Code CLI
model = "claude-sonnet-4.5"
permission_mode = "yolo"          # Auto-approve all permissions (YOLO mode)
timeout_minutes = 60
no_commit = false                 # Set to true to review changes before committing
EOF

# Now `mr run` uses your config
mr run                           # Uses claude-sonnet-4.5, auto-approves, times out after 60min

Available runners:

copilot (default) — Uses gh copilot CLI (requires gh and Copilot subscription)
claude — Uses Claude Code CLI (requires claude CLI and Anthropic API key)
More runners coming soon (Gemini, OpenAI, etc.)

Permission modes:

manual (default) — Agent asks before dangerous operations
yolo — Auto-approve everything (great for trusted PRDs, terrible for unknown code)

Editing PRDs: When Plans Change

PRDs aren't set in stone. Life happens. Scope creeps. Here's how to adapt:

# Light edits: Just open the file
vim .mr/prds/PRD-0005-add-tests.md   # Change task priorities, add notes

# Heavy edits: Let the LLM help
mr edit PRD-0005 "Split T-008 into three tasks: unit tests, integration tests, E2E tests"
# Agent asks clarifying questions, updates the PRD

# Context-heavy edits: Provide upfront context
mr edit PRD-0005 --context "The auth system changed, update all tasks to use JWT"
# Agent uses context to guide questions

Pro tip: Don't delete tasks—mark them status: parked instead. The History section is your audit trail.

Troubleshooting: When Things Go Sideways

Agents aren't perfect. Here's how to recover:

# Task failed? Check the History
cat .mr/prds/PRD-0003-add-auth.md  # Scroll to History section
# Look for "❌ Failed" entries with failure details

# Retry the same task
mr run PRD-0003                    # Agent reads History, tries a different approach

# Skip a task manually
vim .mr/prds/PRD-0003-add-auth.md  # Change task status from `todo` to `parked`
mr run                             # Moves to next task

# Check what the agent actually did
git log -1 --stat                  # See last commit
git diff HEAD~1                    # Review changes

# Revert if needed
git reset --hard HEAD~1            # Undo last commit (if not pushed)
mr run                             # Try again

Pro tip: The History section is gold. If a task keeps failing, read past attempts—the agent learns from its mistakes (kinda).

Finalizing: Closing the Loop

All tasks done? Time to wrap it up:

# 1. Verify all tasks complete
mr status                        # Should show "0 tasks remaining"

# 2. Run UAT verification
mr run PRD-0003                  # If UATs are unverified, agent enters verification loop
                                 # For each UAT: verify, create test, or opt-out

# 3. Finalize the PRD
mr finalize PRD-0003             # Marks as `done`, appends summary to History

# 4. Celebrate
git log --oneline --graph        # Admire your git history
mr list                          # All green checkmarks

Pro tip: UATs (User Acceptance Tests) are defined in PRD frontmatter. They must be verified before finalization. If you skip verification, microralph won't let you finalize.

Multi-PRD Juggling: Parallel Workflows

Got multiple PRDs? microralph handles it:

# Create multiple PRDs
mr new add-auth
mr new refactor-db
mr new fix-ui-bugs

# microralph picks highest-priority task across ALL active PRDs
mr run                           # Might pick T-001 from PRD-0005 (priority 1)
mr run                           # Might pick T-002 from PRD-0003 (priority 2)

# Force work on specific PRD
mr run PRD-0004                  # Only run tasks from this PRD

# Check progress across all PRDs
mr status                        # Shows status of all active PRDs

Pro tip: Use priority numbers to control execution order. Priority 1 = highest. If two tasks have the same priority, microralph picks the older PRD first.

Dev Containers: Sandboxed Ralph-ing

Worried about AI-generated code trashing your machine? Use dev containers:

# 1. Generate dev container config
mr devcontainer generate         # Analyzes repo, creates .devcontainer/devcontainer.json

# 2. Open in container (VSCode)
# VSCode will prompt: "Reopen in Container" → Click it

# 3. Or use CLI
devcontainer up --workspace-folder .
devcontainer exec --workspace-folder . bash

# 4. Ralph safely inside the sandbox
mr run                           # All changes isolated to container

Pro tip: Dev containers also ensure consistent tooling across your team. No more "works on my machine" excuses.

Flags and Options: Power User Mode

Combine flags for maximum control:

# Verbose mode (see all the internals)
mr run --verbose

# Quiet mode (just the facts)
mr run --quiet

# Custom model for expensive tasks
mr run --model claude-opus-4-20250514

# Stream + specific PRD + custom model
mr run PRD-0003 --stream --model gpt-5.2-codex --verbose

# List with custom output
mr list --verbose                # More details in PRDS.md

Pro tip: --verbose shows token usage, model calls, and timing info. Great for debugging or cost tracking.

Quick Reference: Command Cheat Sheet

Scenario	Command	What It Does
Start new project	`mr init`	Creates `.mr/` structure
Bootstrap existing	`mr bootstrap`	Scans repo, generates PRDs
Get AI suggestions	`mr suggest`	Analyzes codebase, suggests 5 PRDs
Create PRD	`mr new <slug>`	Guided Q/A creates PRD
Create PRD with context	`mr new <slug> --context "..."`	Skips some questions
Edit PRD	`mr edit <id> "<request>"`	LLM helps edit PRD
Edit constitution	`mr constitution edit "<request>"`	LLM updates project rules
Run next task	`mr run`	Picks highest-priority task
Run from specific PRD	`mr run <id>`	Only this PRD's tasks
Stream output	`mr run --stream`	Watch agent work live
Check progress	`mr status`	Summary of all PRDs
List PRDs	`mr list`	Regenerates index
Finalize PRD	`mr finalize <id>`	Mark done, append summary
Reindex	`mr reindex`	Fix PRD cross-links
Generate dev container	`mr devcontainer generate`	Create `.devcontainer/devcontainer.json`
Refactor codebase	`mr refactor`	AI-driven iterative improvements
Focused refactor	`mr refactor --context "..."`	Target specific improvement areas
Preview refactors	`mr refactor --dry-run`	See suggestions without applying

Common Workflows: Real-World Scenarios

"I want to add a feature to my app"

mr new add-user-profiles
mr run && mr run && mr run       # Until done
mr finalize PRD-0007

"I bootstrapped and got too many PRDs"

mr list                          # See all PRDs
vim .mr/prds/PRD-0003-*.md       # Change status to `parked`
mr run                           # Only runs active PRDs

"A task keeps failing"

cat .mr/prds/PRD-0005-*.md       # Read History section
mr run PRD-0005 --verbose        # See detailed failure logs
# Manually fix the issue, then:
vim .mr/prds/PRD-0005-*.md       # Update task notes with hints
mr run PRD-0005                  # Try again with new context

"I want to see what the agent is thinking"

mr run --stream --verbose        # Full transparency

"I need to enforce a coding standard"

mr constitution edit "All functions must have type hints"
mr run                           # Agent respects constitution

"I want to ralph faster"

# Use faster model for simple tasks
mr run --model gpt-5-mini

# Use yolo mode (skip permission prompts)
echo 'permission_mode = "yolo"' >> .mr/config.toml
mr run

"I want to clean up my codebase"

# Let AI find and fix issues (3 iterations by default)
mr refactor

# Focus on specific improvements
mr refactor --context "improve error handling"

# Preview suggestions first
mr refactor --dry-run

# Target a specific directory
mr refactor --path src/api/

Tips and Tricks

Don't fight the loop: Let mr run do its thing. Each invocation is cheap (context-wise). Run it 100 times if needed.
Read the History: Failed tasks leave breadcrumbs. The agent learns from past attempts.
Use priorities wisely: Lower numbers = higher priority. Use priority 1 for blocking tasks.
Stream when debugging: --stream lets you see failures as they happen.
Constitution is your friend: Define rules once, enforce everywhere.
Dev containers for safety: Sandbox AI changes until you trust them.
Commit often: Each mr run commits on success. Use git branches for risky PRDs.
Park, don't delete: Mark tasks as parked instead of deleting. You might need them later.

Development

Most dev workflows run via cargo make.

Prerequisites

# Install cargo-make
cargo install cargo-make

Commands

# Run tests
cargo make test

# Run full CI pipeline (fmt, clippy, test)
cargo make ci

# Format code
cargo make fmt

# Run clippy
cargo make clippy

# Build release
cargo make build-release

# UAT (User Acceptance Tests) — the one true gate
cargo make uat

Principles

No direct API calls: microralph shells out to runner CLIs only
State lives in git: PRDs are Markdown files with YAML frontmatter + History section
One-or-zero tasks per mr run: Each invocation attempts at most one task
Runner can fail: History captures what happened and what to try next
Avoid XML/JSON state blobs: Human-readable Markdown PRDs
cargo make everything: Almost all dev workflows route through cargo make

Prompt Placeholders

microralph uses static prompt files in .mr/prompts/ that support placeholder expansion. If you want to customize prompts, here are the available placeholder variables for each prompt type.

Placeholder Syntax

{{variable}} — Simple string substitution
{{#if variable}}...{{/if}} — Conditional block (renders if variable is truthy/non-empty)
{{#each list}}...{{/each}} — List iteration (use {{@index}} for 0-based index)

run_task.md

Used when executing a task via mr run.

Placeholder	Type	Description
`{{prd_path}}`	string	Absolute path to the PRD file
`{{prd_id}}`	string	PRD identifier (e.g., `PRD-0001`)
`{{prd_title}}`	string	PRD title
`{{next_task_id}}`	string	Task identifier (e.g., `T-001`)
`{{task_title}}`	string	Task title
`{{task_priority}}`	string	Task priority number
`{{task_notes}}`	string	Optional task notes (may be empty)

run_task_finalize.md

Used for the final wrap-up task of a PRD.

Placeholder	Type	Description
`{{prd_id}}`	string	PRD identifier
`{{prd_summary}}`	string	Summary of the PRD

prd_new_round1_questions.md

Used for the first round of questions when creating a new PRD.

Placeholder	Type	Description
`{{slug}}`	string	The slug for the new PRD
`{{user_description}}`	string	Optional initial description from user
`{{user_context}}`	string	Optional upfront context provided by user
`{{#each existing_prds}}`	list	Existing PRDs for context
↳ `{{id}}`	string	PRD identifier
↳ `{{title}}`	string	PRD title
↳ `{{status}}`	string	PRD status (draft/active/done/parked)

prd_new_roundN_questions.md

Used for follow-up rounds of questions during PRD creation.

Placeholder	Type	Description
`{{slug}}`	string	The slug for the new PRD
`{{user_context}}`	string	Optional upfront context provided by user
`{{#each qa_history}}`	list	Previous Q/A pairs
↳ `{{question}}`	string	The question that was asked
↳ `{{answer}}`	string	The user's answer
↳ `{{@index}}`	number	0-based index of the Q/A pair

prd_new_synthesize_prd.md

Used to synthesize the final PRD from collected Q/A.

Placeholder	Type	Description
`{{slug}}`	string	The slug for the new PRD
`{{user_context}}`	string	Optional upfront context provided by user
`{{#each qa_history}}`	list	All Q/A pairs from the session
↳ `{{question}}`	string	The question
↳ `{{answer}}`	string	The answer
`{{#each existing_prds}}`	list	Existing PRDs for context
↳ `{{id}}`	string	PRD identifier
↳ `{{title}}`	string	PRD title

prd_edit.md

Used when editing an existing PRD via mr edit.

Placeholder	Type	Description
`{{prd_path}}`	string	Path to the PRD file
`{{user_request}}`	string	The user's edit request
`{{prd_content}}`	string	Current PRD file content
`{{#each qa_history}}`	list	Follow-up Q/A pairs (if any)
↳ `{{question}}`	string	The question
↳ `{{answer}}`	string	The answer

bootstrap_plan.md

Used during mr bootstrap to analyze the repository.

Placeholder	Type	Description
`{{prd_budget}}`	string	Maximum number of PRDs to generate
`{{#each heuristics}}`	list	Analysis heuristics
↳ `{{description}}`	string	Heuristic description

bootstrap_generate_prds.md

Used to generate PRDs from the bootstrap plan.

Placeholder	Type	Description
`{{plan}}`	string	The generated bootstrap plan
`{{prd_budget}}`	string	Maximum number of PRDs to generate

update_agents.md

Used to update the auto-managed section of AGENTS.md.

Placeholder	Type	Description
`{{agents_content}}`	string	Current AGENTS.md content
`{{#each recent_changes}}`	list	Recent file changes
↳ `{{file}}`	string	File path that was changed
↳ `{{description}}`	string	Description of the change

adapt_language.md

Used when initializing for a non-Rust language.

Placeholder	Type	Description
`{{language}}`	string	Target language (e.g., `python`, `node`)
`{{#each build_commands}}`	list	Typical build/test commands
↳ `{{command}}`	string	A build/test command

init.md

Used during mr init. This prompt has no placeholders.

PRD Format

PRDs are Markdown files with YAML frontmatter:

---
id: PRD-0001
title: My Feature
status: active
owner: Your Name
created: 2026-01-23
updated: 2026-01-23

tasks:
  - id: T-001
    title: "Implement the thing"
    priority: 1
    status: todo
---

# Summary

What this PRD is about...

---

# History

(Entries appended by `mr run` will go below this line.)

Learn More

The Ralph Pattern

Ralph is a pattern where you repeatedly invoke an AI coding agent in a loop until a task is complete. The original concept emerged in the AI coding community as a way to overcome context window limitations by running fresh agent sessions iteratively.

A project that is predominantly built this way—a ralph—becomes a testament to the pattern's power: AI does the heavy lifting while you steer with PRDs and review results.

Popular Ralph implementations and resources include:

Ralph: The Ralph Wiggum Technique — Geoffrey Huntley's original post introducing the Ralph loop pattern
soderlind/ralph — Shell script wrapper for GitHub Copilot CLI
Ralph TUI — Terminal UI for Ralph loops
Ralph Loop blog post — Deep dive on the Ralph pattern
The Ralph Wiggum Approach — Long-form article on autonomous coding

How microralph Differs from Basic Ralph

Traditional Ralph implementations are simple loop scripts: run the agent → check if done → repeat. They work well for small tasks but have limitations:

No structure: They don't enforce task breakdown or planning upfront
No persistence: Progress isn't tracked in a human-readable way
No history: Failed attempts aren't logged for future context
One-shot scope: Typically run until a single condition is met, not across multiple tasks

microralph takes the Ralph pattern and adds:

PRD-driven structure: Define all tasks upfront with priorities
One-task-per-run: Each mr run completes exactly one task (no bloat)
Git-native state: PRDs are markdown files that track progress and history
Multi-task orchestration: Automatically picks the next task from active PRDs
Guided workflows: mr new and mr bootstrap help structure work
Runner abstraction: Pluggable backends (Copilot, others to come)

Think of microralph as "Ralph with a project management system built in."

What's a PRD?

A Product Requirements Document (PRD) defines what you want to build. In microralph, PRDs are enhanced with:

Tasks: Atomic units of work with priority and status
History: A log of what the agent attempted and what happened

See Writing Good PRDs for general guidance.

Agent Loops & Context Limits

Modern AI agents suffer from the context window problem: as conversations grow, agents slow down, get expensive, and eventually "forget" earlier context.

microralph implements an agentic loop pattern:

Load minimal context (just the current task + PRD)
Execute the task
Persist results to disk (git-tracked markdown)
Exit—freeing context for the next task

This pattern is inspired by work on:

Agentic Design Patterns by Andrew Ng
ReAct: Reasoning and Acting in Language Models
LangChain Agent Loops

Comparison with Other Tools

Feature	microralph	Claude Code	Cursor	Aider	Cline
PRD-driven task breakdown	✅	❌	❌	❌	❌
One-task-per-run (no bloat)	✅	❌	❌	❌	❌
Git-native state	✅	❌	❌	✅	❌
History/retry logging	✅	❌	❌	⚠️ (partial)	❌
Multi-runner abstraction	✅	❌ (Claude only)	❌ (Cursor only)	⚠️ (multi-model)	❌ (VSCode only)
Works in terminal	✅	✅	❌ (IDE only)	✅	❌ (IDE only)
No API keys required	✅ (uses CLI auth)	✅	✅	❌	✅
Customizable prompts	✅	❌	❌	⚠️	❌

Why microralph is Different

Most AI coding tools are session-based: you start a conversation, describe what you want, and the agent tries to do everything in one go. This works for small tasks but breaks down for larger projects:

Context bloat: Long sessions accumulate context until the agent gets confused
No persistence: If you close the session, you start over
No structure: There's no clear definition of "done" or progress tracking

microralph is task-based: you define discrete tasks upfront, and each mr run tackles exactly one task with fresh context. Progress is tracked in git, so you can close your terminal, reboot your machine, or come back weeks later—microralph picks up where it left off.

Think of it as the difference between "do everything in one meeting" vs. "complete one ticket per sprint" — the latter scales.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 421 Commits
.config		.config
.github/workflows		.github/workflows
.mr		.mr
src		src
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
DEVELOPMENT.md		DEVELOPMENT.md
LICENSE		LICENSE
Makefile.toml		Makefile.toml
README.md		README.md
cliff.toml		cliff.toml
rust-toolchain.toml		rust-toolchain.toml

License

twitchax/microralph

Folders and files

Latest commit

History

Repository files navigation

microralph

What is a Ralph?

The Real Value: Locking Time for Artisanal Code

Why microralph?

The Normal Flow

Features

Installation

Pre-built Binaries (Recommended)

Linux

Mac OS (Apple Silicon)

Windows

Cargo

WebAssembly (via OCI Registry)

From Source

Usage

Commands

Flags

Configuration

Dev Containers

Why Use Dev Containers?

Supported Workflows

Generating Dev Container Configs

Dev Container Warnings

Regenerating After Changes

Restoring Prompts and Templates

How It Works

Reviewing Changes

Important Notes

Use Cases

Constitution

What's the Constitution For?

How It Works

Example Constitution

Editing the Constitution

Enforcement Model

User Flows

The Complete microralph Experience

Starting Fresh: The New Project Flow

Adding to Existing: The Bootstrap Flow

Day-to-Day: The Task Loop Flow

Advanced: Constitution-Driven Development

Configuration: Making microralph Yours

Editing PRDs: When Plans Change

Troubleshooting: When Things Go Sideways

Finalizing: Closing the Loop

Multi-PRD Juggling: Parallel Workflows

Dev Containers: Sandboxed Ralph-ing

Flags and Options: Power User Mode

Quick Reference: Command Cheat Sheet

Common Workflows: Real-World Scenarios

"I want to add a feature to my app"

"I bootstrapped and got too many PRDs"

"A task keeps failing"

"I want to see what the agent is thinking"

"I need to enforce a coding standard"

"I want to ralph faster"

"I want to clean up my codebase"

Tips and Tricks

Development

Prerequisites

Commands

Principles

Prompt Placeholders

Placeholder Syntax

run_task.md

run_task_finalize.md

prd_new_round1_questions.md

prd_new_roundN_questions.md

prd_new_synthesize_prd.md

prd_edit.md

bootstrap_plan.md

bootstrap_generate_prds.md

update_agents.md

adapt_language.md

Packages