[](https://github.com/twitchax/microralph/actions/workflows/build.yml)
[](https://codecov.io/gh/twitchax/microralph)
[](https://crates.io/crates/microralph)
[](https://github.com/twitchax/microralph/releases)
[](https://opensource.org/licenses/MIT)
# 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](https://docs.github.com/en/copilot/using-github-copilot/using-github-copilot-chat-in-your-ide), [Claude Code CLI](https://docs.anthropic.com/en/docs/build-with-claude/claude-for-command-line), and [OpenAI Codex CLI](https://github.com/openai/codex)) 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](https://en.wikipedia.org/wiki/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:
1. **Breaking work into discrete tasks** via PRDs
2. **Running one task per invocation** so context never bloats
3. **Persisting state in git-tracked Markdown** so the agent can pick up where it left off
4. **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 interactively β
β 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
- **Interactive PRD creation**: `mr new` drops you into a direct chat with the AI agent 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, Claude, Codex, mock for testing)
## Installation
### Pre-built Binaries (Recommended)
Download pre-built binaries from [GitHub Releases](https://github.com/twitchax/microralph/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
```bash
$ 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)
```bash
$ 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
```powershell
$ 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
```bash
$ 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.
```bash
# 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:
```bash
# 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
```bash
git clone https://github.com/twitchax/microralph.git
cd microralph
cargo install --path .
```
## Usage
```bash
# 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 interactive chat
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 interactive chat |
| `mr new <slug> --context` | Create a new PRD with upfront context for the interactive session |
| `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 run --disallow-skip-uat` | Prevent the agent from marking UATs as skipped |
| `mr run --disallow-add-task` | Prevent the agent from adding new tasks to the PRD during execution |
| `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`, `codex`, `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`:
```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](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) 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](https://github.com/devcontainers/cli) to build and run containers from the terminal:
```bash
# 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:
```bash
mr devcontainer generate
```
This command:
1. Scans your repository structure (languages, frameworks, dependencies)
2. Analyzes git history for recently added tools
3. Reads PRDs for tool references
4. 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:
```bash
# 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:
1. **Reset customizations**: Revert custom prompts/templates back to microralph's defaults
2. **Update to latest built-ins**: Pull in updated prompts/templates after upgrading microralph
3. **Compare customizations**: Use Git diff to review your changes against the latest defaults
#### How It Works
```bash
mr restore
```
The command:
1. Deletes `.mr/prompts/` and `.mr/templates/` directories
2. Recreates them with built-in defaults (same logic as `mr init`)
3. Leaves changes **uncommitted** so you can review via Git
#### Reviewing Changes
After running `mr restore`, use Git to see what changed:
```bash
# 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**
```bash
mr restore
git diff # Review what changed
git add .mr/ # Commit to accept defaults
```
**Scenario 2: You upgraded microralph and want new prompt features**
```bash
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**
```bash
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
1. **Bootstrap creates it**: When you run `mr init` or `mr bootstrap`, microralph creates `.mr/constitution.md` with commented-out example rules.
2. **Version controlled**: The constitution is committed to git alongside your PRDs.
3. **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.
4. **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").
5. **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
```markdown
# 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:
```bash
# 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:
```bash
# 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 # Interactive chat 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:
```bash
# 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:
```bash
# 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:
```bash
# 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:
```bash
# 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
# Or use OpenAI Codex CLI
mr run --runner codex --model o4-mini --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:
```bash
# 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:
```bash
# 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:
```bash
# 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:
```bash
# 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:
```bash
# 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:
```bash
# 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>` | Interactive chat creates PRD |
| Create PRD with context | `mr new <slug> --context "..."` | Provides context for the chat session |
| 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"
```bash
mr new add-user-profiles
mr run && mr run && mr run # Until done
mr finalize PRD-0007
```
#### "I bootstrapped and got too many PRDs"
```bash
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"
```bash
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"
```bash
mr run --stream --verbose # Full transparency
```
#### "I need to enforce a coding standard"
```bash
mr constitution edit "All functions must have type hints"
mr run # Agent respects constitution
```
#### "I want to ralph faster"
```bash
# 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"
```bash
# 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
```bash
# Install cargo-make
cargo install cargo-make
```
### Commands
```bash
# 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_interactive.md
Used for the single-phase interactive PRD creation. The agent gathers info from the user and writes the PRD file directly to disk.
| Placeholder | Type | Description |
| ------------------------- | ------ | ----------------------------------------- |
| `{{slug}}` | string | The slug for the new PRD |
| `{{next_id}}` | string | The next PRD ID (e.g., PRD-0004) |
| `{{prd_path}}` | string | Target file path for the PRD |
| `{{user_description}}` | string | Optional initial description from user |
| `{{user_context}}` | string | Optional upfront context provided by user |
| `{{constitution}}` | string | Project constitution content |
| `{{#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_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:
```markdown
---
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](https://ghuntley.com/ralph/) β Geoffrey Huntley's original post introducing the Ralph loop pattern
- [soderlind/ralph](https://github.com/soderlind/ralph) β Shell script wrapper for GitHub Copilot CLI
- [Ralph TUI](https://ralph-tui.com/) β Terminal UI for Ralph loops
- [Ralph Loop blog post](https://benjamin-abt.com/blog/2026/01/19/ralph-loop-github-copilot-cli-dotnet/) β Deep dive on the Ralph pattern
- [The Ralph Wiggum Approach](https://dev.to/sivarampg/the-ralph-wiggum-approach-running-ai-coding-agents-for-hours-not-minutes-57c1) β 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:
1. **PRD-driven structure**: Define all tasks upfront with priorities
2. **One-task-per-run**: Each `mr run` completes exactly one task (no bloat)
3. **Git-native state**: PRDs are markdown files that track progress and history
4. **Multi-task orchestration**: Automatically picks the next task from active PRDs
5. **Guided workflows**: `mr new` and `mr bootstrap` help structure work
6. **Runner abstraction**: Pluggable backends (Copilot, Claude, Codex)
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](https://www.atlassian.com/agile/product-management/requirements) 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:
1. Load minimal context (just the current task + PRD)
2. Execute the task
3. Persist results to disk (git-tracked markdown)
4. Exitβfreeing context for the next task
This pattern is inspired by work on:
- [Agentic Design Patterns](https://www.deeplearning.ai/the-batch/agentic-design-patterns-part-1/) by Andrew Ng
- [ReAct: Reasoning and Acting in Language Models](https://arxiv.org/abs/2210.03629)
- [LangChain Agent Loops](https://python.langchain.com/docs/modules/agents/)
## 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