The Goal: Fully Autonomous Workflows

By default, the codex exec command is interactive, requiring user approval to proceed. This is great for safety but hinders full automation. We needed a hands-free loop that could run continuously on a trusted workstation, keeping work moving forward without manual intervention while adhering to strict safety protocols.

The core challenge was to eliminate the "continue?" prompts and approval gates that slowed down automated tasks. We also needed to solve for context drift by fixing the working directory and ensure that sensitive information never appeared on the command line.

TL;DR

  • The "Ralph Loop" script automates codex exec by running it in a continuous, hands-free cycle, bypassing interactive approval prompts for efficiency.
  • It maintains context by locking the working directory and automatically injects the highest-priority task at the start of each run.
  • Safety is a core design feature, with rules to prevent publishing secrets, limiting execution to trusted workstations, and keeping all external communications in a draft state.
"The best way to predict the future is to invent it."— Alan Kay

Solution: The Ralph Loop Runner

Our solution is a script that wraps codex exec in a persistent loop, guided by a specialized prompt that sets the rules for autonomous operation.

  • Autopilot Prompt: A file located at ~/.codex/hooks/ralph-loop.prompt.md establishes the agent's rules: no pausing unless a command is destructive, ambiguous, or missing secrets; report status after each subtask; and ensure all communications are drafts only.
  • Loop Runner Script: The core script at ~/.codex/hooks/ralph-loop.sh launches codex exec with flags to enforce the working directory (-C <workdir>), bypass approvals, and disable the sandbox on a trusted host. It runs in a perpetual loop with a configurable backoff period.
  • Dynamic Task Injection: Before each run, the script prepends the highest-priority "bead" (our unit of work) into the prompt, focusing the agent on the most current task.
  • Documentation: Instructions are available in ~/.codex/hooks/README.md and the project's own README.md.

Quick Start

Run the script in the foreground:

# foreground
~/projects/ralph-loop-runner/ralph-loop.sh /home/jason/projects/big-brain

Or run it in the background with logging:

# background with logging
LOG_FILE=/tmp/ralph.log ~/projects/ralph-loop-runner/start.sh /home/jason/projects/big-brain

Watch the running processes:

# watch processes
ps -u $USER -o pid,cmd | grep 'codex exec'

Operational Helpers

  • Healthcheck Script: Verify the loop is running with ~/projects/ralph-loop-runner/healthcheck.sh.
  • Systemd Integration: A sample systemd user unit is provided in the README for running the script as a managed service.
  • Log Rotation: The README also includes a sample configuration for managing log files.

How It Works

  1. The script reads the autopilot prompt file to establish operational rules.
  2. It injects the current highest-priority task into the prompt.
  3. It executes codex exec with flags to set the work directory, skip the git check, and bypass approvals and the sandbox.
  4. After the run completes, it sleeps for a few seconds and then restarts the cycle.

Safety Guardrails

  • Trusted Host Only: The sandbox bypass is explicit and should only be used on a secure, local machine.
  • Draft-Only Communications: The system prompt strictly forbids the agent from sending communications directly, ensuring a human reviews them first.
  • No Secrets on the Command Line: The agent is instructed to use secure, out-of-band methods for secrets.
  • Explicit Approval Policy: The approval policy defaults to never unless explicitly overridden with the APPROVAL_POLICY environment variable.

Configuration Knobs

  • SLEEP_SECONDS: Controls the backoff time between runs.
  • CODEX_BIN: Specifies an alternate path for the codex binary.
  • Prompt File: The agent's rules and voice can be edited in the prompt file without modifying the runner script.

Pitfalls to Avoid

  • Do not use --cwd, which is an invalid flag; always use -C to specify the working directory.
  • Ensure the loop script is executable (chmod +x).
  • Never run this on an untrusted host with the sandbox bypass enabled.
  • Always monitor the logs when running the script in the background to catch potential issues early.