v0.3.0

Highlights

ralph add — install ralphs from GitHub

Share and reuse ralphs across projects. Fetch from any GitHub repo and run by name:

ralph add owner/repo/my-ralph    # Install a specific ralph
ralph add owner/repo              # Install all ralphs in a repo
ralph run my-ralph                # Run it by name

Installed ralphs live in .ralphify/ralphs/ (gitignored, disposable).

{{ ralph.* }} placeholders

Ralphs can now reference runtime metadata — {{ ralph.name }}, {{ ralph.iteration }}, and {{ ralph.max_iterations }} — without any frontmatter configuration.

Two-stage Ctrl+C

First Ctrl+C gracefully finishes the current iteration. Second Ctrl+C force-stops immediately. Agent subprocesses now run in their own process group for reliable cleanup.

Iteration monitor UI

Iteration results are now rendered as markdown using Rich, with a polished run header and cleaner formatting. Thanks to @malpou for contributing this improvement!

---

Full changelog: v0.2.3...v0.3.0

PyPI: https://pypi.org/project/ralphify/0.3.0/

v0.2.3

Added

• Co-authored-by credit trailer — every prompt now includes an instruction telling the agent to add Co-authored-by: Ralphify <noreply@ralphify.co> to commit messages. On by default; opt out with credit: false in RALPH.md frontmatter.

Improved

• Typed event payloads — replaced dict[str, Any] event data with TypedDict classes throughout the engine and console emitter for stronger type safety.
• Code quality — standardized imports, extracted constants, simplified TypedDicts with NotRequired.

Full changelog: v0.2.2...v0.2.3

PyPI: https://pypi.org/project/ralphify/0.2.3/

v0.2.2

Added

• ralph init command — scaffold a new ralph with a ready-to-customize template, no AI agent required. Run ralph init my-task to create a directory with a RALPH.md that includes example commands, args, and placeholders. A faster alternative to the AI-guided ralph new.

Full changelog: v0.2.1...v0.2.2

PyPI: https://pypi.org/project/ralphify/0.2.2/

v0.2.1

Fixed

• {{ args.* }} placeholders now resolved in command run strings — previously, arg placeholders were only resolved in the prompt body. Commands like run: gh issue view {{ args.issue }} would fail because shlex.split tokenized the raw placeholder into multiple arguments. Args are now resolved before command execution. (#20)

v0.2.0 — The v2 Rewrite

The v2 rewrite. Ralphify is now simpler: a ralph is a directory with a RALPH.md file. No more ralph.toml, no more .ralphify/ directory, no more ralph init. Everything lives in one file.

Breaking changes

• Removed ralph.toml — the agent command is now in the agent field of RALPH.md frontmatter
• Removed ralph init — create a ralph directory with a RALPH.md file manually, or use ralph new
• Removed .ralphify/ directory — no more checks, contexts, or named ralphs as separate primitives
• Removed checks and contexts — replaced by commands in RALPH.md frontmatter
• ralph run requires a path — ralph run my-ralph instead of ralph run with optional name
• Placeholder syntax changed — {{ contexts.<name> }} is now {{ commands.<name> }}
• User arguments — now passed after -- separator: ralph run my-ralph -- --dir ./src

Added

• commands frontmatter field — define commands that run each iteration directly in RALPH.md
• Single-file configuration — agent, commands, args, and prompt all live in one RALPH.md file

Fixed

• Guard against double-starting a run in RunManager
• Eliminate TOCTOU race in RunManager.start_run
• UTF-8 encoding for all subprocess calls
• Stricter input validation (whitespace-only fields, negative delay, duplicate command names, command timeout)
• Clear command placeholders when no commands exist
• Error handling for os.execvp in ralph new

Improved

• Extensive test coverage for agent, events, console emitter, engine internals, and frontmatter
• Code quality: named constants, consolidated test helpers, compiled regexes

Upgrade guide

See the full changelog for step-by-step migration instructions from 0.1.x.

Install: pip install ralphify==0.2.0 or uv pip install ralphify==0.2.0

v0.1.12 — new tagline

Changed

• New tagline — updated project tagline to "Stop stressing over not having an agent running. Ralph is always running" across CLI, PyPI, and docs.

Improved ralph new experience

Improved ralph new experience

No more permission prompts

ralph new now launches Claude Code with --dangerously-skip-permissions, so the AI-guided setup flow runs without interruptions.

Just describe what you want

The setup skill no longer asks you about checks, contexts, or frontmatter. Just describe what you want to automate in plain English:

ralph new my-task
> "I want to write tests for my Python project until I hit 90% coverage"

The agent figures out the right checks, contexts, and prompt structure for you.

User arguments awareness

The skill now knows about user arguments and will suggest {{ args.name }} placeholders when a ralph would benefit from being reusable across different projects or configurations.

Full changelog: v0.1.10...v0.1.11

v0.1.10

User arguments for ralphs

Ralphs can now accept user arguments from the CLI, making them reusable across different projects and configurations.

Pass --name value flags or positional arguments to ralph run:

ralph run research --dir ./my-project --focus "performance"

Reference them in your RALPH.md with {{ args.name }} placeholders:

---
description: Research agent
args: [dir, focus]
---
Research the codebase at {{ args.dir }}.
Focus area: {{ args.focus }}

Context and check scripts receive user arguments as RALPH_ARG_<KEY> environment variables.

See the CLI reference and primitives docs for full details.

New documentation

• Quick reference — single-page cheat sheet for CLI commands, directory structure, frontmatter fields, and placeholders
• Prompt writing guide — best practices for writing effective RALPH.md prompts
• "How it works" — explains the iteration lifecycle and system model
• "When to use" — helps evaluate whether ralph loops fit your task
• Agent comparison table — side-by-side comparison of supported agents with output behavior notes
• Expanded cookbook — new recipes for Python, TypeScript, Rust, Go, bug fixing, codebase migration, and multi-ralph project setup

Fixed

• Malformed ralph.toml now shows a helpful error message instead of a raw KeyError.

v0.1.9

What's Changed

Breaking Changes

• Explicit primitive dependencies — Global checks and contexts (.ralphify/checks/, .ralphify/contexts/) are no longer auto-applied to all ralphs. They are now a library of available primitives. Ralphs must explicitly declare which globals they use via frontmatter:

  ---
  checks: [lint, typecheck]
  contexts: [git-log, codebase-map]
  ---

  Ralph-local primitives (inside the ralph's own directory) still auto-apply. Unknown names produce a clear error listing available primitives. Ad-hoc prompts (-p) receive no global primitives.

• Named context placeholders required — The bulk {{ contexts }} placeholder and implicit context append have been removed. All contexts must be referenced by name: {{ contexts.git-log }}.

• Unknown ralph names rejected — Passing a value to ralph run that doesn't match a named ralph now errors instead of silently treating it as an inline prompt.

• ralph status removed — Validation (check script executability, etc.) now runs at ralph run startup instead.

Features

• Auto-reload primitives — Primitives are re-discovered every iteration so edits on disk take effect immediately without manual reload.
• Port 3000 default — Listen on port 3000 to match Coolify's default Traefik config.

Fixes

• Remove unused imports flagged by ruff.

Migration Guide

To migrate from 0.1.8, add checks and contexts lists to your RALPH.md frontmatter declaring which global primitives each ralph uses. For example, if you had a global check lint and context git-log that previously auto-applied:

---
checks: [lint]
contexts: [git-log]
---
Your prompt here with {{ contexts.git-log }}

Full Changelog: v0.1.8...v0.1.9

v0.1.8

What's Changed

Features

• AI-guided ralph new — replaced static scaffolding with an interactive AI skill that helps you create new ralphs
• Simplified UX — removed the instructions primitive, run banner, and added RALPH.md protection
• RALPH_NAME env var — now passed to context and check scripts so they can adapt per-ralph
• Simplified CLI — removed ralphs and ui subcommands; ralph is now the default primitive type for new
• Renamed "prompt" to "ralph" — the prompt primitive is now called "ralph" and .ralph/ is now .ralphify/
• Spinner with elapsed time — iterations now show a spinner with elapsed time instead of silent waiting
• Landing page — added ralphify.co website with build pipeline

Bug Fixes

• Set status to STOPPED on KeyboardInterrupt instead of COMPLETED
• Restored agent result message in CLI output after each iteration
• Fixed Docker build for mkdocs git-revision-date plugin (git init, git identity, git install)

Refactoring

• Introduced Primitive protocol for typed discovery and display functions
• Introduced Named protocol and generic typing for merge_by_name
• Extracted shared scanning logic in _discovery.py to reduce duplication
• Moved discover_enabled wiring into primitive modules to reduce engine coupling
• Encapsulated streaming vs blocking agent mode selection in _agent.py
• Flattened streaming loop nesting with guard clauses
• Renamed internal functions for clarity (_execute_agent → _run_agent_phase)

Documentation

• Major docs overhaul — removed speculative/bloated pages (FAQ, best-practices, why-ralphify, quick-reference, how-it-works, ralphs.md)
• Added Python API reference for programmatic embedding
• Added UX simplification research and architecture analysis
• Simplified getting started guide and updated codebase map
• Added changelog entry for 0.1.7 breaking rename

Full Changelog: v0.1.7...v0.1.8