Skip to main content
Unlisted page
This page is unlisted. Search engines will not index it, and only users having a direct link can access it.

Code Factory + Ralph: Autonomous Coding Loop

· 3 min read

Source: Ryan Carson's articles | compound-product repo | Ralph guide Authors: Ryan Carson (@ryancarson), Geoffrey Huntley (Ralph pattern), Kieran Klaassen (Compound Engineering) Tweet: 3,751 likes

The Goal​

One loop:

  1. The coding agent writes code
  2. The repo enforces risk-aware checks before merge
  3. A code review agent validates the PR
  4. Evidence (tests + browser + review) is machine-verifiable

Ralph: The Autonomous Loop​

Ralph is a bash loop that ships features while you sleep:

  1. Pipes a prompt into your AI agent
  2. Agent picks the next story from prd.json
  3. Implements it
  4. Runs typecheck and tests
  5. Commits if passing
  6. Marks the story done
  7. Logs learnings to progress.txt
  8. Repeats until done

File Architecture​

FilePurpose
ralph.shThe executable loop script
prompt.mdIteration-specific instructions
prd.jsonTask inventory (branchName, priority, passes)
progress.txtLearnings across iterations (agent appends after each story)
AGENTS.mdPreserved patterns and conventions

Compound-Product System​

4 phases:

  • Phase 0: Generate daily reports
  • Phase 1: Analyze reports using LLM API
  • Phase 2: Planning with AI agents -> create prd.json executable tasks
  • Phase 3: Execution loop (loop.sh) -- runs up to N iterations
./scripts/compound/auto-compound.sh          # full run
./scripts/compound/auto-compound.sh --dry-run # dry run
./scripts/compound/loop.sh 10                # just the loop

5 Critical Success Factors​

  1. Small Stories -- tasks must fit within single context windows
  2. Fast Feedback -- typecheck and tests must execute quickly
  3. Explicit Criteria -- clear completion definitions
  4. Pattern Accumulation -- by iteration 10, agent understands patterns from previous stories
  5. Documentation Updates -- AGENTS.md preserves reusable patterns

The Contract​

Define a contract specifying:

  • Risk tiers by path -- what scrutiny different codebase parts get
  • Required checks by tier -- what must pass per risk level
  • Docs drift rules for control-plane changes
  • Evidence requirements for UI/critical flows -- browser recordings, screenshots

Code Factory Workflow​

  • Risk tiers: Low (automate fully), Medium (automate with gates), High (require human confirmation)
  • Preflight gate must complete before CI fanout -- deterministic ordering
  • Review state: valid only when matching current PR head commit SHA (non-negotiable)
  • Deterministic rerun: one canonical workflow as rerun requester, dedupe by marker + sha:<head>
  • Evidence capture: tests + browser recordings + review, all machine-verifiable
  • Auto-resolve: only bot-only stale threads after clean rerun
  • Browser automation: agent-browser for screenshots and video evidence attached to PRs
  • Remediation agent: fixes review issues in-branch, reruns deterministically

Review Agents (Pluggable)​

The control-plane pattern is agent-agnostic. Options:

  • Greptile
  • CodeRabbit AI
  • CodeQL + policy logic
  • Custom LLM review

Installation​

git clone https://github.com/snarktank/compound-product.git
cd compound-product
./install.sh /path/to/your/project

Config (compound.config.json):

{
  "tool": "amp" or "claude",
  "reportsDir": "reports/",
  "qualityChecks": ["npm run typecheck", "npm test"],
  "maxIterations": 10,
  "branchPrefix": "compound/"
}

Not Suitable For​

  • Exploratory work
  • Major refactors without clear criteria
  • Security-sensitive code
  • Anything requiring human review of nuance

Code Factory cover