feat: add ralph-cli skill and replace Aider with Pi

README.md

@@ -44,7 +44,7 @@ ralph run grow-coverage     # loops until Ctrl+C
 
 That's loop engineering in three lines: a prompt, a command for live data, and the runtime. Each iteration starts with a **fresh context window** and **current data** — ralphify runs the commands, fills in the `{{ placeholders }}`, pipes the prompt to your agent, and loops. Walk away, come back to a pile of commits.
 
-*Works with any agent CLI. Swap `claude -p` for Codex, Aider, or your own — just change the `agent` field.*
+*Works with any agent CLI. Swap `claude -p` for Codex, Pi, or your own — just change the `agent` field.*
 
 ## Install
 
@@ -169,7 +169,7 @@ Full docs at **[ralphify.co/docs](https://ralphify.co/docs/)** — getting start
 ## Requirements
 
 - Python 3.11+
-- An agent CLI that accepts piped input ([Claude Code](https://docs.anthropic.com/en/docs/claude-code), Codex, Aider, or your own)
+- An agent CLI that accepts piped input ([Claude Code](https://docs.anthropic.com/en/docs/claude-code), Codex, Pi, or your own)
 
 ## License
 

agr.lock

@@ -38,6 +38,10 @@ installed-name = "code-review"
 path = "skills/ralphify-release"
 installed-name = "ralphify-release"
 
+[[skill]]
+path = "./skills/ralph-cli"
+installed-name = "ralph-cli"
+
 [[ralph]]
 path = "ralphs/bug-hunter"
 installed-name = "bug-hunter"

agr.toml

@@ -28,6 +28,7 @@ dependencies = [
     {path = "ralphs/bug-hunter", type = "ralph"},
     {path = "skills/ralphify-release", type = "skill"},
     {handle = "computerlovetech/ralphs/improve-codebase", type = "ralph"},
+    {path = "./skills/ralph-cli", type = "skill"},
 ]
 
 [[source]]

docs/cli.md

@@ -118,7 +118,7 @@ The compact peek panel shows the ten most recent activity lines. Press **shift+P
 | `[` / `]` | Browse to the previous / next iteration |
 | `q` or `P` | Exit back to the compact view |
 
-Live streaming works with line-buffered agents such as Claude Code, OpenAI Codex, and Aider. Agents that repaint their own terminal UI (full-screen curses or TUI apps) are not supported — ralphify pipes their stdio, so they detect a non-TTY and fall back to plain output. If lines appear in bursts rather than as produced, set `PYTHONUNBUFFERED=1` (or the equivalent) in the environment where you launch `ralph`.
+Live streaming works with line-buffered agents such as Claude Code, OpenAI Codex, and Pi. Agents that repaint their own terminal UI (full-screen curses or TUI apps) are not supported — ralphify pipes their stdio, so they detect a non-TTY and fall back to plain output. If lines appear in bursts rather than as produced, set `PYTHONUNBUFFERED=1` (or the equivalent) in the environment where you launch `ralph`.
 
 ### `ralph scaffold`
 
@@ -238,7 +238,7 @@ Ralphify works with **any CLI that reads a prompt from stdin and exits when done
 | Agent | Stdin support | Streaming | Wrapper needed |
 |---|---|---|---|
 | [Claude Code](#claude-code) | Native (`-p`) | Yes — real-time activity tracking | No |
-| [Aider](#aider) | Via bash wrapper | No | Yes (`bash -c`) |
+| [Pi](#pi) | Native (`-p`) | No | No |
 | [Codex CLI](#codex-cli) | Native (`exec`) | No | No |
 | [Custom](#custom-wrapper-script) | You implement it | No | Yes (script) |
 
@@ -254,17 +254,17 @@ agent: claude -p --dangerously-skip-permissions
 
 `-p` enables non-interactive mode (reads prompt from stdin, prints output, exits). `--dangerously-skip-permissions` skips approval prompts so the agent works autonomously — without it, the agent would hang forever waiting for approval that nobody is there to give. Install with `npm install -g @anthropic-ai/claude-code`. When the command starts with `claude`, ralphify automatically adds `--output-format stream-json --verbose` for activity tracking and result-text extraction.
 
-### Aider
+### Pi
 
-[Aider](https://aider.chat) doesn't natively read prompts from stdin, so wrap it with `bash -c` and `cat -`:
+[Pi](https://pi.dev) is a minimal coding-agent CLI. Its print mode reads the piped prompt from stdin natively, so no wrapper is needed:
 
 ```markdown
 ---
-agent: bash -c 'aider --yes-always --no-auto-commits --message "$(cat -)"'
+agent: pi -p -a
 ---
 ```
 
-`--yes-always` auto-approves changes; `--no-auto-commits` lets your prompt control commits. Add `--model claude-sonnet-4-6` (or another) to pick a model.
+`-p` enables print mode (non-interactive: reads the piped prompt from stdin, prints the response, exits). `-a` (`--approve`) trusts the project-local Pi config and extensions for the run so the loop runs unattended. Install with `npm install -g --ignore-scripts @earendil-works/pi-coding-agent` or `curl -fsSL https://pi.dev/install.sh | sh`.
 
 ### Codex CLI
 

docs/diary/2026-06-09-ralph-cli-skill-and-pi-swap.md

@@ -0,0 +1,142 @@
+# Diary: ralph-cli skill + replace Aider with Pi
+
+Two related pieces of work in one session: (1) author a new `ralph-cli` agent
+skill modeled on the existing `agr-cli` skill, install it via agr; (2) replace
+every Aider suggestion across the project with Pi (pi.dev).
+
+## Step 1: Create the ralph-cli skill
+
+**Author:** main
+
+### Prompt Context
+
+**Verbatim prompt:** "look in ../agr/skills/agr-cli . I want to make a similar
+skill for ralphif ralph-cli. Please write it and use agr to install it."
+**Interpretation:** Study the `agr-cli` SKILL.md + references as a template, and
+produce an analogous skill that teaches an agent to operate the `ralph` CLU /
+ralphify, then register it with `agr add`.
+**Inferred intent:** Ship a first-class, in-repo skill so any agent working in
+ralphify (or a downstream consumer) can drive `ralph` correctly — scaffold,
+write RALPH.md, run loops, pick agents, debug, use the Python API.
+
+### What I did
+Read `/Users/kasperjunge/Code/agr/skills/agr-cli/SKILL.md` to learn the
+structure (frontmatter description, "When to use", mental model, numbered
+workflows, boundaries, references index). Grounded the content in the real CLI
+surface by running `ralph --help`, `ralph run --help`, `ralph scaffold --help`
+and reading `/docs/cli.md` and the example `/ralphs/example/RALPH.md`.
+
+Scaffolded with `agr init ralph-cli`, moved it under `/skills/ralph-cli/`, and
+wrote `SKILL.md` plus six reference files: `writing-ralphs.md`, `running.md`,
+`the-loop.md`, `agents.md`, `troubleshooting.md`, `python-api.md`. Registered it
+with `agr add ./skills/ralph-cli`, which added `{path = "./skills/ralph-cli",
+type = "skill"}` to `/agr.toml` and installed a copy into
+`/.claude/skills/ralph-cli`.
+
+### Why
+The user explicitly asked for a sibling skill to `agr-cli`. Splitting depth into
+`references/` keeps the top-level SKILL.md scannable while letting an agent load
+detail on demand — the same pattern agr-cli uses.
+
+### What worked
+`ralph --help` and the existing `docs/cli.md` gave a complete, authoritative
+surface, so the skill didn't need guesswork. `agr init` + `agr add ./path`
+registered the in-repo skill cleanly on the first try.
+
+### What didn't work
+First `Write` of SKILL.md failed: "File has not been read yet" — `agr init` had
+already created a scaffold SKILL.md, so it had to be `Read` before overwriting.
+Re-read, then wrote successfully.
+
+### What I learned
+ralphify ships ralphs as an agr resource `type = "ralph"` (visible in
+`agr.toml`), distinct from `type = "skill"`. The skill's boundaries call this
+out so it defers install/sync mechanics to the `agr-cli` skill and keeps its own
+scope on authoring + running ralphs.
+
+### What was tricky
+Scoping the description's trigger terms. "ralph", "RALPH.md", and "loop
+engineering" are extremely common in this very repo, so the skill will activate
+often here. I flagged that to the user rather than silently narrowing it.
+
+### What warrants review
+The SKILL.md description trigger breadth (over-activation risk in-repo). And the
+factual accuracy of `references/python-api.md` against the actual `ralphify`
+package exports — it was derived from `docs/cli.md`, which should be canonical,
+but worth a sanity check.
+
+### Future work
+None required; the user immediately moved on to the Pi swap.
+
+## Step 2: Replace Aider with Pi across the project
+
+**Author:** main
+
+### Prompt Context
+
+**Verbatim prompt:** "remove suggestions about aider across the project.
+Replace wiht Pi from pi.dev"
+**Interpretation:** Every place the docs/skill/examples suggest Aider as an
+agent option should instead suggest Pi (the coding agent at pi.dev), with
+correct invocation.
+**Inferred intent:** Standardize the recommended non-Claude/non-Codex agent on
+Pi everywhere a reader might copy it.
+
+### What I did
+`grep -rin aider` to enumerate hits, then looked up Pi's real invocation via
+WebFetch/WebSearch against pi.dev and `earendil-works/pi` docs before writing
+any config — established that Pi's print mode (`-p`) reads piped stdin natively
+and that `-a`/`--approve` trusts project-local config for unattended runs.
+
+Replaced Aider with Pi in: `/README.md`, `/docs/index.md`, `/docs/cli.md` (agent
+table row + the full `### Aider` → `### Pi` section), `/docs/llms.txt`,
+`/docs/llms-full.txt` (taglines, table, the full Aider section incl. the
+"specific model" variant and the standalone test snippet),
+`/examples/optimize-docs/RALPH.md`, and the `ralph-cli` skill
+(`SKILL.md`, `references/agents.md`, `references/running.md`). Used `sed` for the
+one-line list swaps and `Edit` for the structural sections.
+
+In `/tests/test_agent.py` and `/tests/test_console_emitter.py`, "aider" was only
+a generic non-Claude placeholder agent in fixtures, so I swapped it to "pi"
+(still non-Claude, non-stream-json — behavior unchanged). Left the two mentions
+in `/tasks/done/` alone — those are archived completed-task write-ups, i.e.
+historical narrative, not user-facing suggestions.
+
+Reinstalled the skill with `agr add ./skills/ralph-cli --overwrite`.
+
+### Why
+The user wanted Aider gone "across the project." Pi is a genuine improvement to
+document because, unlike Aider, it needs no `bash -c '... "$(cat -)"'` wrapper —
+the config collapses to `agent: pi -p -a`.
+
+### What worked
+`pytest tests/test_agent.py tests/test_console_emitter.py` → 229 passed, 1
+xpassed. `mkdocs build --strict` → clean, zero warnings. Final
+`grep -rin aider` showed only the intentional `tasks/done/` leftovers.
+
+### What didn't work
+One `Edit` on `docs/llms-full.txt` failed with "File has been modified since
+read" (a linter/formatter touched it between my Read and Edit). Re-read the
+exact line range and re-applied — succeeded.
+
+### What I learned
+Pi install is `npm install -g --ignore-scripts @earendil-works/pi-coding-agent`
+or `curl -fsSL https://pi.dev/install.sh | sh`. Print mode merges piped stdin
+into the prompt, and `--approve`/`-a` governs trust of project-local
+inputs/extensions (not tool-action auto-approval — non-interactive print mode is
+inherently non-prompting). I verified this rather than guessing flags.
+
+### What was tricky
+Deciding scope of "across the project." I included the generated-but-committed
+`llms*.txt` mirrors and the test fixtures, but deliberately excluded
+`tasks/done/` history. Called that boundary out to the user.
+
+### What warrants review
+The `pi -p -a` recommendation — confirm `-a` is the desired default for
+unattended loops vs. relying on a saved trust decision. Also the `llms-full.txt`
+Pi section, which I rewrote by hand since there's no generator script in the repo
+(`scripts/` only has `tui_dev/`).
+
+### Future work
+If ralphify later adds a generator for `llms.txt`/`llms-full.txt`, the
+hand-edited Pi content should be reconciled with it.

docs/index.md

@@ -47,7 +47,7 @@ ralph run grow-coverage     # loops until Ctrl+C
 
 Each iteration starts with a **fresh context window** and **current data** — ralphify runs the commands, fills in the `{{ placeholders }}`, pipes the prompt to your agent, and loops.
 
-*Works with any agent CLI. Swap `claude -p` for Codex, Aider, or your own — just change the `agent` field.*
+*Works with any agent CLI. Swap `claude -p` for Codex, Pi, or your own — just change the `agent` field.*
 
 [Get Started](getting-started.md){ .md-button .md-button--primary }
 [The ralph loops format](https://ralphloops.io/){ .md-button }

docs/llms-full.txt

@@ -43,7 +43,7 @@ ralph run grow-coverage     # loops until Ctrl+C
 
 One directory. One command. Each iteration starts with fresh context and current data — ralphify runs the commands, fills in `{{ placeholders }}`, pipes the prompt to your agent, and loops.
 
-Works with any agent CLI. Swap `claude -p` for Codex, Aider, or your own — just change the `agent` field.
+Works with any agent CLI. Swap `claude -p` for Codex, Pi, or your own — just change the `agent` field.
 
 ## Install
 
@@ -586,7 +586,7 @@ This page shows how to configure the `agent` field in your RALPH.md for popular
 | Agent | Stdin support | Streaming | Wrapper needed |
 |---|---|---|---|
 | [Claude Code](#claude-code) | Native (`-p`) | Yes — real-time activity tracking | No |
-| [Aider](#aider) | Via bash wrapper | No | Yes (`bash -c`) |
+| [Pi](#pi) | Native (`-p`) | No | No |
 | [Codex CLI](#codex-cli) | Native (`exec`) | No | No |
 | [Custom](#custom-wrapper-script) | You implement it | No | Yes (script) |
 
@@ -643,33 +643,32 @@ This enables ralphify to:
 - Track agent activity in real time
 - Extract the final result text from the agent's response
 
-## Aider
+## Pi
 
-[Aider](https://aider.chat) is an AI pair-programming tool that works with multiple LLM providers.
+[Pi](https://pi.dev) is a minimal coding-agent CLI. Its print mode reads the piped prompt from stdin natively, so no wrapper is needed.
 
 ```markdown
 ---
-agent: bash -c 'aider --yes-always --no-auto-commits --message "$(cat -)"'
+agent: pi -p -a
 ---
 ```
 
 | Flag | Purpose |
 |---|---|
-| `--yes-always` | Auto-approve all changes (no interactive prompts) |
-| `--no-auto-commits` | Let your prompt control when commits happen |
-| `--message "..."` | Pass the prompt as a message instead of stdin |
+| `-p` | Print mode — non-interactive: reads the piped prompt from stdin, prints output, exits |
+| `-a` / `--approve` | Trust the project-local Pi config and extensions for the run so the loop runs unattended |
 
-Why the bash wrapper?
+Install Pi:
 
-Aider doesn't natively read prompts from stdin. The `bash -c` wrapper reads stdin with `cat -` and passes it as a `--message` argument.
+```bash
+npm install -g --ignore-scripts @earendil-works/pi-coding-agent
+# or
+curl -fsSL https://pi.dev/install.sh | sh
+```
 
-### Aider with a specific model
+Why `-p`?
 
-```markdown
----
-agent: bash -c 'aider --yes-always --no-auto-commits --model claude-sonnet-4-6 --message "$(cat -)"'
----
-```
+Print mode is non-interactive — it reads the assembled prompt straight from stdin and exits when done, exactly what an autonomous loop needs. Because Pi reads stdin natively, there's no `bash -c` wrapper to write.
 
 ## Codex CLI
 
@@ -731,7 +730,7 @@ Verify the agent works outside of ralphify first. The command depends on which a
     ```
 
     ```bash
-    echo "Say hello and nothing else" | bash -c 'aider --yes-always --no-auto-commits --message "$(cat -)"'
+    echo "Say hello and nothing else" | pi -p -a
     ```
 
     ```bash
@@ -1935,7 +1934,7 @@ The loop also stops automatically when:
 
 When you run `ralph run` in an interactive terminal, the agent's stdout and stderr stream live to the console by default. Press `p` to silence the stream (useful for quieter loops) and press `p` again to resume it. The default is off whenever the output is not a real terminal (piped, redirected, or captured in CI), so `ralph run ... | cat` is unaffected.
 
-Live streaming works with line-buffered agents such as Claude Code, OpenAI Codex, Aider, and any other process that writes one line at a time. When `--log-dir` is set, output is captured to the log file and also echoed after each iteration completes; live peek still works the same way in that mode.
+Live streaming works with line-buffered agents such as Claude Code, OpenAI Codex, Pi, and any other process that writes one line at a time. When `--log-dir` is set, output is captured to the log file and also echoed after each iteration completes; live peek still works the same way in that mode.
 
 ---
 

docs/llms.txt

@@ -40,7 +40,7 @@ ralph run my-ralph         # loop until Ctrl+C
 ralph run my-ralph -n 5    # run 5 iterations
 ```
 
-Works with any agent CLI — swap `claude -p` for Codex, Aider, or your own.
+Works with any agent CLI — swap `claude -p` for Codex, Pi, or your own.
 
 ## Why a format
 
@@ -52,7 +52,7 @@ Everyone writing ralph loops ends up with the same scaffolding: a markdown promp
 - **Live steering**: Edit `RALPH.md` while the loop runs. Changes take effect on the next iteration.
 - **Fresh context every cycle**: No conversation bloat or hallucinated memories. The agent reads current codebase state each time.
 - **Progress in git**: Every iteration commits to git. Roll back with `git reset` if needed.
-- **Any agent**: Works with Claude Code, Aider, Codex CLI, or any CLI that reads stdin.
+- **Any agent**: Works with Claude Code, Pi, Codex CLI, or any CLI that reads stdin.
 - **Shareable ralphs**: Ralphs are just directories — share via git repos, install with [agr](https://github.com/computerlovetech/agr).
 
 ## Placeholder types
@@ -80,7 +80,7 @@ Embed the loop in automation pipelines. See the API docs for details.
 
 - [Getting Started](https://ralphify.co/docs/getting-started/): Install to running loop in 10 minutes
 - [How it Works](https://ralphify.co/docs/how-it-works/): Iteration lifecycle details
-- [Using with Different Agents](https://ralphify.co/docs/agents/): Claude Code, Aider, Codex CLI setup
+- [Using with Different Agents](https://ralphify.co/docs/agents/): Claude Code, Pi, Codex CLI setup
 - [Cookbook](https://ralphify.co/docs/cookbook/): Copy-pasteable recipes for coding, docs, research
 - [CLI Reference](https://ralphify.co/docs/cli/): All commands and options
 - [Python API](https://ralphify.co/docs/api/): Programmatic usage

examples/optimize-docs/RALPH.md

@@ -62,7 +62,7 @@ content. Then:
   developers actually type
 - Add clear `description` and `keywords` to frontmatter — base these
   on actual search intent, not just the page content
-- Research what terms competing tools (aider, cursor, claude-code,
+- Research what terms competing tools (pi, cursor, claude-code,
   copilot) rank for and use relevant ones
 - Target long-tail keywords around specific tasks ("run AI agent in
   loop", "automate coding agent prompts")