Using with Different Agents¶
TL;DR
Set the agent field in your RALPH.md to any CLI that reads a prompt from stdin and exits when done. Claude Code (claude -p --dangerously-skip-permissions) is the default with the deepest integration. Aider needs a bash -c wrapper to pass stdin as --message. Codex CLI works natively with codex exec. For anything else, write a short wrapper script.
Ralphify works with any CLI that reads a prompt from stdin and exits when done. Claude Code is the default, but you can use any tool that follows this contract.
This page shows how to configure the agent frontmatter field in your RALPH.md for popular agents and how to write your own wrapper.
Agent comparison¶
| Agent | Stdin support | Streaming | Wrapper needed |
|---|---|---|---|
| Claude Code | Native (-p) |
Yes — real-time activity tracking | No |
| Aider | Via bash wrapper | No | Yes (bash -c) |
| Codex CLI | Native (exec) |
No | No |
| Custom | You implement it | No | Yes (script) |
If you're not sure which to pick: start with Claude Code. It has the deepest integration, the best autonomous coding capabilities, and is the default.
What ralphify needs from an agent¶
Every iteration, ralphify runs your agent like this:
Your agent must:
- Read a prompt from stdin — the full assembled prompt is piped in
- Do work in the current directory — edit files, run commands, make commits
- Exit when done — exit code 0 means success, non-zero means failure
That's it. No special protocol, no API — just stdin in, work done, process exits.
Claude Code¶
The default and recommended agent.
| Flag | Purpose |
|---|---|
-p |
Non-interactive mode — reads prompt from stdin, prints output, exits |
--dangerously-skip-permissions |
Skips approval prompts so the agent can work autonomously |
Install Claude Code:
Why --dangerously-skip-permissions?
Without this flag, Claude Code pauses to ask for approval before editing files, running commands, or making commits. In an autonomous loop, nobody is there to approve — so the agent would hang forever. Commands in your RALPH.md act as your guardrails instead.
Automatic streaming mode¶
When ralphify detects that the agent command starts with claude, it automatically adds --output-format stream-json --verbose to the command. You don't need to add these flags yourself.
This enables ralphify to:
- Parse Claude Code's structured JSON output line by line
- Track agent activity in real time
- Extract the final result text from the agent's response
Aider¶
Aider is an AI pair-programming tool that works with multiple LLM providers.
| 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 |
Why the bash wrapper?
Aider doesn't natively read prompts from stdin. The bash -c wrapper reads stdin with cat - and passes it as a --message argument.
Aider with a specific model¶
---
agent: bash -c 'aider --yes-always --no-auto-commits --model claude-sonnet-4-6 --message "$(cat -)"'
---
Codex CLI¶
OpenAI Codex CLI supports non-interactive use natively via its exec subcommand.
| Flag | Purpose |
|---|---|
exec |
Non-interactive mode — designed for piped/scripted use |
--sandbox danger-full-access |
Full filesystem access for autonomous operation |
- |
Read prompt from stdin |
Custom wrapper script¶
For full control, write a wrapper script that reads stdin and calls your agent however it needs to be called.
ralph-agent.sh
#!/bin/bash
set -e
# Read the prompt from stdin
PROMPT=$(cat -)
# Call your agent however it works
my-custom-agent --input "$PROMPT" --auto-approve
my-ralph/RALPH.md
Testing your setup¶
Verify the agent works outside of ralphify first. The command depends on which agent you're using:
If the agent prints a response and exits, your setup is working. If it hangs or errors, fix the agent installation before continuing.
Then test through ralphify with a single iteration using ralph run:
Non-Claude-Code agents
Disable auto-commits if your prompt handles commits — most agents have this feature, and it conflicts with prompt-driven commit instructions. Use --timeout as a safety net in case the agent enters an unexpected interactive mode.
How agent output works¶
Ralphify streams agent output line-by-line in both execution modes. In an interactive terminal, output streams live to the console by default — press p to silence it and p again to resume. See Peeking at live agent output for details.
When --log-dir is set, output is captured to a log file and also echoed after each iteration completes. Live peek still works the same way in that mode.
Streaming mode (Claude Code)¶
When the agent command starts with claude, ralphify parses the agent's structured JSON output line by line. This enables additional features beyond live output:
- Activity tracking — the terminal shows what the agent is doing (tool calls, reasoning) in real time
- Result text extraction — the agent's final response is captured separately
- Verbose logging — with
--log-dir, logs include the agent's internal tool calls and reasoning
Blocking mode (all other agents)¶
For non-Claude agents, ralphify spawns the process and drains stdout and stderr through background reader threads. You see the agent's plain text output line by line as it's produced.
Both modes support all ralphify features (commands, timeouts, iteration tracking, live peek). The difference is that Claude Code gets structured activity tracking on top of the raw output.
Adapting other tools¶
Many AI coding tools don't read from stdin directly but can be adapted with a bash wrapper. The pattern is:
The cat - reads the piped prompt from stdin and passes it as a command-line argument. This works for any tool that accepts a prompt via a flag (like --message, --input, --prompt).
If the tool has no way to accept a prompt non-interactively, a custom wrapper script is the escape hatch — you can use the prompt text however the tool needs it.
Next steps¶
- Getting Started — set up your first loop with the agent you just configured
- Troubleshooting — when the agent hangs, produces no output, or exits unexpectedly