How It Works

Ralph workflow idea

Ralph runs with --dangerously-skip-permissions (or similar), which means it has full access to whatever credentials are available inside the container. The Dev Container setup limits blast radius by:

The Dev Container acts as a hard boundary. VS Code credential-forwarding is neutralized by apostStarthook before Ralph runs. The only credential Ralph ever sees is a fine-grained PAT you mount from your host — scoped to one repo.

VSCode dev container is well integrated with VSCode IDE which makes it convenient to quickly reopens project in container anytime.

ralph-workflow provide convenience for you to scaffolds those things up

HOST MACHINEHOST ONLY🔑 SSH keys🐙 Full GitHub session☁️ Cloud credentials🏢 All org repos✗ NOT accessible in containerFine-grained PAT(mount from host)Dev ContainerBlanked by postStart hook✗GIT_ASKPASS✗VSCODE_GIT_ASKPASS✗VSCODE_GIT_IPC_HANDLE✗SSH_AUTH_SOCK✗GITHUB_TOKEN (VS Code session)Ralph + AI CLI--dangerously-skip-permissionsreads/writes/runs commands freelyinside container onlyAccessible to RalphFine-grained PATscope: 1 repo • Contents: writeRepo code (cloned)read + write within container
Credential blankingA postStart script clears VS Code's credential-forwarding env vars (GIT_ASKPASS, VSCODE_GIT_*, SSH_AUTH_SOCK, GITHUB_TOKEN) before Ralph ever runs.
Fine-grained PATEven with full freedom inside the container, Ralph can only push to the single repository the PAT is scoped to. Your host SSH keys, other GitHub repos, cloud accounts, and org-wide access are never reachable.
Blast radius limitationEven if Ralph goes off-script, it can only push to the single repository the PAT is scoped to. No access to other repos, cloud accounts, or host SSH keys.

The Ralph Loop

Ralph is a bash loop that drives an AI CLI through your task list until every story is marked done.

Readprd.yamlLoadcontextPipe toAI CLIImplement& testCommitMark done& logAll done?not done → repeat
  1. 01

    Read prd.yaml prd.yaml

    Each iteration Ralph reads prd.yaml and picks the highest-priority story where passes: false.

  2. 02

    Load codebase context progress.txt

    progress.txt is read for accumulated patterns and gotchas from previous iterations, giving Ralph growing institutional knowledge.

  3. 03

    Pipe prompt to AI CLI ralph.sh

    ralph.sh pipes prompt.md through the chosen AI CLI (claude, codex, gemini, or opencode) with --dangerously-skip-permissions so it can read, write, and run commands autonomously.

  4. 04

    Implement & test prompt.md

    The agent implements the story, runs typecheck and tests. If they fail, it fixes and retries within the same iteration.

  5. 05

    Commit the change ralph.sh

    On passing checks the agent commits with the message format feat: [ID] - [Title], creating a clean, traceable history.

  6. 06

    Mark done & log learnings progress.txt

    prd.yaml is updated to passes: true and new patterns are appended to progress.txt for future iterations.

  7. 07

    Check completion ralph.sh

    If all stories pass, the agent outputs <promise>COMPLETE</promise> and ralph.sh exits successfully. Otherwise the loop repeats.

Key Files

ralph.sh

The iteration loop. Pipes prompt.md into the AI CLI and checks for the COMPLETE marker.

prompt.md

Per-iteration instructions. Tells the agent which story to pick, how to commit, and when to stop.

prd.yaml

Your task list. Stories with passes: false are picked up; Ralph flips them to true when done.

progress.txt

Accumulated codebase patterns. Ralph reads this at the start of each iteration and appends new learnings at the end.