microralph-0.1.0 is not a library.

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) 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: 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

Cargo

cargo install microralph

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 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

Flag	Description
`-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:

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 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

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

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 include:

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

microralph 0.1.0

microralph

What is a Ralph?

The Real Value: Locking Time for Artisanal Code

Why microralph?

The Normal Flow

Features

Installation

Cargo

From Source

Usage

Commands

Flags

Configuration

Dev Containers

Why Use Dev Containers?

Supported Workflows

Generating Dev Container Configs

Dev Container Warnings

Regenerating After Changes

Constitution

What's the Constitution For?

How It Works

Example Constitution

Editing the Constitution

Enforcement Model

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

init.md

PRD Format

Learn More

The Ralph Pattern

How microralph Differs from Basic Ralph

What's a PRD?

Agent Loops & Context Limits

Comparison with Other Tools

Why microralph is Different

License