Using with Different Agents¶

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 field in your RALPH.md for popular agents and how to write your own wrapper.

Agent comparison¶

Agent	Stdin support	Streaming	`ralph new` support	Wrapper needed
Claude Code	Native (`-p`)	Yes — real-time activity tracking	Yes	No
Aider	Via bash wrapper	No	No	Yes (`bash -c`)
Codex CLI	Via bash wrapper	No	Yes	Yes (`bash -c`)
Custom	You implement it	No	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:

echo "<assembled prompt>" | <agent command>

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.

---
agent: claude -p --dangerously-skip-permissions
---

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:

npm install -g @anthropic-ai/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.

---
agent: bash -c 'aider --yes-always --no-auto-commits --message "$(cat -)"'
---

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 can be configured to run non-interactively.

---
agent: bash -c 'codex --approval-mode full-auto "$(cat -)"'
---

Flag	Purpose
`--approval-mode full-auto`	Skip all approval prompts for autonomous operation

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

chmod +x ralph-agent.sh

my-ralph/RALPH.md

---
agent: ./ralph-agent.sh
---

Your prompt here.

Testing your setup¶

Verify the agent works outside of ralphify first:

echo "Say hello" | <your-agent-command>

Then test through ralphify with a single iteration:

ralph run my-ralph -n 1 --log-dir ralph_logs

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 uses two different execution modes depending on the agent:

Streaming mode (Claude Code)¶

When the agent command starts with claude, ralphify spawns the process with Popen and reads its JSON output line by line. This enables:

Live activity tracking — the terminal shows what the agent is doing in real time
Result text extraction — the agent's final response is captured
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 uses subprocess.run and waits for the process to exit. Output behavior depends on whether you're using --log-dir:

Without --log-dir — agent output streams directly to your terminal in real time
With --log-dir — output is captured, written to a log file, then replayed to the terminal after the iteration completes

Both modes support all ralphify features (commands, timeouts, iteration tracking). The difference is only in how output is handled during each iteration.

Adapting other tools¶

Many AI coding tools don't read from stdin directly but can be adapted with a bash wrapper. The pattern is:

bash -c '<tool> <auto-approve-flag> --message "$(cat -)"'

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.