ralphy-agent 0.1.2
Deterministic autonomous agent loop for executing PRDs one story at a time
Requires Python: >=3.12

# ralphy

**ralphy** is a deterministic autonomous agent loop for executing PRDs one story at a time, inside a real codebase.

ralphy orchestrates an external **agent CLI** to perform execution.
By default this is OpenAI Codex, but the agent command is fully configurable.

ralphy is a Python implementation of the informal “Ralph Wiggum technique”: assume the agent is simple-minded, reduce its cognitive load, and put the intelligence in the environment (tight inputs, validation, retries, and hard failures).

ralphy is not a chatbot.
ralphy is not an agent framework.
ralphy is a loop that values clarity over cleverness.

---

## Status (today)

As of 2026-01-22, ralphy is an early scaffold with:

- `ralphy config validate` (validates `ralphy.toml`)
- `ralphy prd [--workspace <name>]` (creates `.ralphy/workspaces/<name>/prd.json`)
- `ralphy init` (creates `.ralphy/` project layout)
- `ralphy [--workspace <name>]` (bootstraps/selects a run; creates `.ralphy` & `ralphy.toml` if missing; currently prints the run id)

If `--workspace` is omitted, ralphy generates a short workspace name and prints it.

For detailed UX/user flows and the “fast path” commands, see `docs/ux.md`.

For a detailed explanation of the on-disk runtime layout, see `docs/layout.md`.

For how to publish releases to PyPI, see `docs/releasing.md`.

---

## What ralphy aims to do (planned)

ralphy repeatedly:

1. Selects exactly one unfinished story from an active PRD run
2. Renders a prompt for that story
3. Spawns a fresh agent process in the current repository
4. Executes the story in isolation
5. Runs quality checks
6. Records results and commits changes if successful
7. Stops when all stories are complete or a limit is reached

There is **no conversational memory**.
All memory lives on disk.

---

## Installation

ralphy is distributed as a standard Python CLI.

### Install globally

```bash
pip install ralphy
```

Verify:

```bash
ralphy --help
```

### Workspaces (parallel instances)

To run multiple Ralphy instances in the same repo at the same time, use separate workspaces.
Each workspace has isolated state under `.ralphy/workspaces/<name>/`.

```bash
ralphy --workspace a
ralphy --workspace b
```

---

### Run without installing (recommended for experimentation)

```bash
uvx ralphy --help
```

For local-from-source development (this repo), run:

```bash
uvx --from . ralphy --help
```

All commands work the same:

```bash
uvx ralphy prd --workspace dev
uvx ralphy --workspace dev
```

---

### Development setup (using uv)

```bash
git clone https://github.com/your-org/ralphy.git
cd ralphy
uv sync
source .venv/bin/activate
ralphy --help
```

---

## Core concepts

### Agent execution

ralphy executes an **external agent command** defined in configuration.

Examples:

```
AGENT_CMD="codex exec --yolo -"
AGENT_CMD="claude -p --dangerously-skip-permissions \"$(cat {prompt})\""
AGENT_CMD="droid exec --skip-permissions-unsafe -f {prompt}"
AGENT_CMD="opencode run \"$(cat {prompt})\""
```

ralphy:

* Writes a prompt file
* Substitutes `{prompt}` with the file path
* Executes the command in the project root
* Captures stdout, stderr, and exit status

The agent is treated as an unsafe but useful subprocess.

---

### PRDs vs PRD runs

A **PRD** is a validated `prd.json` file.

A **PRD run** is an executable instance of a PRD with its own:

* state
* progress log
* iteration history
* optional git branch

Creating a PRD does not start execution.
Starting a run always requires an explicit PRD.

### On-disk state (`.ralphy/`)

All mutable runtime state is stored under `.ralphy/` in the repo root.

See `docs/layout.md` for a full tree and “what to inspect” cheat sheet.

---

## Configuration

ralphy reads configuration from a project-local file.
On first run, if `ralphy.toml` does not exist, ralphy creates a default config and uses it.

Example:

```toml
# ralphy.toml

[agent]
command = "codex exec --yolo -"

[execution]
max_iterations = 10
enable_git = false
```

### Override the agent per run

Planned: allow overriding the configured agent command per invocation via a CLI flag (e.g. `--agent=codex`).

Missing or invalid configuration causes a hard failure.

Examples:

- Minimal sample config: `docs/examples/ralphy.toml`
- Minimal sample PRD: `docs/examples/prd.json`

---

## Technical stack (intentional)

ralphy deliberately uses a small set of boring, proven Python libraries.

These choices are part of the design.

* **pydantic**
  State, config, and PRD validation.
  Guarantees explicit contracts and fail-fast behavior.

* **typer**
  CLI structure and help text.
  Keeps commands readable and predictable.

* **pathlib**
  All filesystem interactions.
  Prevents path bugs and improves clarity.

* **subprocess / shlex**
  Agent execution and isolation.
  The boundary between orchestration and execution.

* **structlog**
  Structured event logging.
  Enables auditability (what ran, when, and why it failed or succeeded).

* **file locking**
  Prevents concurrent runs and state corruption.