v0.4.0b3

Improved

• Full-screen peek scrollbar — a scrollbar on the right edge of the full-screen peek view shows your position in the activity log, so you always know where you are in a long session.
• Thinking traces visible — agent reasoning (thinking blocks) now appears in the activity feed as dim italic text instead of being silently dropped. Long thinking traces are split by newline so you can scroll through the full reasoning.
• Full text and tool args — assistant text output is no longer truncated to 100 characters, and tool parameters for Agent and ToolSearch now show their actual values (description, prompt, query, max_results) instead of just listing parameter names.
• Context token display — token counts in the panel title now show as ctx 156k · out 3.2k instead of ↑156k ↓3.2k, making context window usage immediately clear.
• Persistent Shift+P hint — the compact panel footer now always shows "Shift+P full screen" so new users discover full-screen peek without reading docs.
• Clearer page navigation labels — the full-screen footer now says b page up · space page down instead of the ambiguous b/space page.

Fixed

• HTML comments in code blocks — <!-- --> comments inside fenced code blocks in RALPH.md files no longer break prompt assembly.

v0.4.0b2

Added

• Full-screen peek (shift+P) — the compact peek panel only shows the ten most recent activity lines, so earlier tool calls from a long iteration scrolled out of view. Press shift+P to open a full-screen, scrollable view of the entire activity buffer on the terminal's alt screen. Navigate with j/k (line), space/b (page), g/G (top/bottom), and q or P to exit. Agent activity keeps streaming in while you scroll, and scrolling back to the bottom re-enables follow mode. The view auto-exits when the iteration ends, so you're never stuck in an alt screen showing dead buffer. The scroll buffer now keeps up to 5000 lines per iteration (was 50) so full-screen peek has something to show.

Fixed

• Peek toggle now restores previous terminal state — toggling peek off used to leave the live activity region in the scrollback, so returning to the compact view looked different from before you pressed p. The peek region is now transient: toggling off restores the terminal to exactly the state it was in before peek was enabled, matching the behavior pre-0.4.0.
• Peek scroll buffer preserved across toggles — hitting p to hide peek used to drop the scroll buffer, so toggling back on showed an empty feed until new activity arrived. The buffer now survives toggles, so you immediately see the latest state on re-enable.
• Double-slash in shortened paths — _shorten_path now correctly handles absolute paths outside $HOME (e.g. /usr/local/...), producing /…/file.py instead of //…/file.py in the activity feed.

---

Install: uv tool install ralphify==0.4.0b2

v0.4.0b1

What's new

Structured live activity panel for Claude agents

When running ralph run with a Claude agent, pressing p now shows a compact, readable activity panel instead of raw JSON noise. The panel shows:

• Live spinner with elapsed time and token counts
• Current tool in progress (e.g. → Bash uv run pytest)
• Scrolling log of tool calls and assistant messages
• Model name and tool category breakdown

Non-Claude agents keep the previous raw-line output. The panel is best-effort — a rendering failure never interrupts the run loop.

Also in this release

• Live output streaming — agent output streams to console by default; p toggles visibility
• ralph scaffold — replaces ralph init
• ralph add / ralph new removed — use agr for ralph installation
• Many reliability fixes — frontmatter parsing, Rich markup injection, timeout enforcement, process cleanup, keypress listener resilience

Breaking changes

• ralph init → ralph scaffold
• Installed ralphs moved from .ralphify/ralphs/ to .agents/ralphs/
• AgentResult.returncode is None on timeout (was kill signal code)
• ralph add and ralph new removed

Full changelog: v0.3.0...v0.4.0b1

PyPI: https://pypi.org/project/ralphify/0.4.0b1/

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