[](https://github.com/twitchax/microralph/actions/workflows/build.yml)
[](https://codecov.io/gh/twitchax/microralph)
[](https://crates.io/crates/microralph)
[](https://opensource.org/licenses/MIT)
# microralph
> *A small ralph to help you ralph your ralphs.* 🦙
**microralph** is a tiny CLI that wraps your favorite AI coding agent (starting with [GitHub Copilot CLI](https://docs.github.com/en/copilot/using-github-copilot/using-github-copilot-chat-in-your-ide)) 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**. 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 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
### Cargo
```bash
cargo install microralph
```
### 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 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
| `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 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 reindex` | Regenerate index and verify/fix PRD interlinks |
| `mr status` | Show status of PRDs and tasks |
### Flags
| `-v, --verbose` | Enable verbose output |
| `-q, --quiet` | Suppress non-essential output |
| `--runner <runner>` | Specify runner (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-20250514"
permission_mode = "yolo"
timeout_minutes = 30
```
CLI flags override config file settings.
### 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
npm install -g @devcontainers/cli
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
### 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
## 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`.
| `{{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.
| `{{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.
| `{{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.
| `{{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.
| `{{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`.
| `{{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.
| `{{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.
| `{{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.
| `{{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.
| `{{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 include:
- [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, 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](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
| **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