fabis-ralph-loop

CLI for setting up and running Claude Ralph autonomous coding loops in Docker containers.

Define a fabis-ralph-loop.config.ts, then use the CLI to generate Docker artifacts, manage the container lifecycle, and run iterative autonomous coding loops. Each iteration, a Claude agent picks the next user story from a PRD, implements it, runs quality checks, commits, and stops — then a fresh session picks up the next one.

Install

pnpm add fabis-ralph-loop

Requires Node.js >= 22.

Quick Start

# 1. Scaffold config file and generate all files
npx fabis-ralph-loop init

# 2. Edit fabis-ralph-loop.config.ts to match your project

# 3. Regenerate files after config changes
npx fabis-ralph-loop generate

# 4. Start the container (auto-attaches a shell)
npx fabis-ralph-loop start

Before starting the container, prepare a PRD using the generated skills in your IDE:

/prd                    # describe your feature → .ralph/prd-feature.md
/ralph                  # convert PRD to JSON → .ralph/prd.json

Then inside the container, kick off the loop:

# Run 20 iterations of the autonomous coding loop
run-fabis-ralph-loop 20

# Override the model
run-fabis-ralph-loop 20 --model opus

# Enable verbose progress output
run-fabis-ralph-loop 20 --verbose

run-fabis-ralph-loop is a wrapper script installed in the container's PATH that pins the same CLI version as the host. Ctrl+C gracefully stops the current iteration; pressing it twice force-exits.

How It Works

1. Generate — fabis-ralph-loop generate creates Docker artifacts (.ralph-container/), a prompt template (ralph-prompt.md), and AI skills
2. Prepare a PRD — Use /prd in your IDE to write a Product Requirements Document, then /ralph to convert it into .ralph/prd.json
3. Start — fabis-ralph-loop start builds the container image, starts it, runs the entrypoint (git safety, auth validation, direnv, setup hooks), then drops you into a shell
4. Run the loop — run-fabis-ralph-loop <iterations> feeds the prompt to the Claude agent each iteration. The agent reads the PRD, picks the highest-priority incomplete story, implements it, runs backpressure commands (lint, typecheck, tests), commits, and stops. The next iteration picks up the next story.
5. Completion — When all stories pass, the agent outputs a completion signal and the loop exits early

The container is sandboxed: git pushes are blocked, and each iteration runs in a fresh agent session so context doesn't leak between stories.

Configuration

Create a fabis-ralph-loop.config.ts in your project root:

import { defineConfig } from 'fabis-ralph-loop'

export default defineConfig({
  project: {
    name: 'my-project',
    description: 'What the project does',
    context: 'Additional context for the AI agent',
    backpressureCommands: [
      { name: 'typecheck', command: 'pnpm tsc --noEmit' },
      { name: 'lint', command: 'pnpm eslint .' },
    ],
  },
  container: {
    name: 'my-project-ralph',
    playwright: true, // auto-configures Playwright CLI + headless Chromium (or 'mcp' for MCP mode)
    sslCerts: '.certs', // trust custom SSL certs in container (for local HTTPS dev servers)
    blockedDomains: ['figma.com', 'linear.app'], // block MCP server domains not needed in autonomous mode
    systemPackages: ['ripgrep'],
    env: { NODE_ENV: 'development' },
    hooks: {
      rootSetup: ['apt-get install -y some-package'],
      userSetup: ['npm install -g some-tool'],
      entrypointSetup: ['pnpm install'],
    },
  },
  defaults: {
    model: 'sonnet',
    sleepBetweenMs: 2000,
  },
  output: {
    mode: 'direct', // or 'uac' for universal-ai-config integration
  },
})

Overrides Config

For environment-specific settings that shouldn't be committed (different models, debug flags, local API keys), create a fabis-ralph-loop.overrides.config.ts:

import { defineOverridesConfig } from 'fabis-ralph-loop'

export default defineOverridesConfig({
  defaults: {
    model: 'opus',
    verbose: true,
  },
  container: {
    env: { DEBUG: 'true' },
  },
})

The overrides file is gitignored automatically by fabis-ralph-loop init. It gets deep-merged on top of the base config: objects merge recursively, arrays are replaced entirely, and scalars are overwritten.

CLI Commands

All commands run on the host machine via npx fabis-ralph-loop <command>:

| Command | Description | | ---------- | --------------------------------------------------------- | | init | Scaffold config and generate all files | | generate | Regenerate files from config | | start | Build and start the container (attaches shell by default) | | stop | Stop and remove the container | | restart | Stop + start the container | | logs | Follow container logs | | run <n> | Execute n loop iterations (can also run from host) | | exec | Run an arbitrary command inside the container |

Notable flags

• generate --dry-run — preview without writing files
• generate --only <container|prompt|skills> — generate a specific subset
• start --no-attach / restart --no-attach — don't attach a shell after starting
• run --model <model> — override the default model
• run --verbose — enable verbose progress output

Inside the container

The container has run-fabis-ralph-loop on the PATH — this is the primary way to kick off loop iterations. It wraps fabis-ralph-loop run pinned to the same version as your host install.

Generated Skills

fabis-ralph-loop generate seeds AI skills into your project that power the Ralph workflow. These are slash commands available to the Claude agent both inside the container and in your IDE:

• /prd — Generate a Product Requirements Document. Describe a feature, answer a few clarifying questions, and get a structured PRD saved to .ralph/prd-<feature>.md.
• /ralph — Convert a PRD into .ralph/prd.json, the structured format the loop consumes. Splits stories into iteration-sized chunks, orders by dependencies, and ensures each has verifiable acceptance criteria.
• /update-fabis-ralph-loop-config — Edit fabis-ralph-loop.config.ts without manually reading the schema. Useful for adding backpressure commands, container packages, env vars, or hooks.

Typical workflow

# In your IDE (before starting the container):
/prd                    # describe your feature, answer questions → .ralph/prd-feature.md
/ralph                  # convert PRD to JSON → .ralph/prd.json

# Inside the container:
run-fabis-ralph-loop 20 # let the loop implement it

What Gets Generated

Running generate creates:

• .ralph-container/Dockerfile — container image with system packages, user setup, and optional Playwright
• .ralph-container/docker-compose.yml — compose config with volumes, networking, and environment
• .ralph-container/entrypoint.ts — container entrypoint that bootstraps the environment
• ralph-prompt.md — the prompt fed to the AI agent each iteration
• Skills — AI tool skills for PRD creation and Ralph workflow (output location depends on output.mode)

Programmatic API

import { loadRalphConfig, generateAll, defineConfig } from 'fabis-ralph-loop'
import type { RalphLoopConfig, ResolvedConfig } from 'fabis-ralph-loop'

const { config, projectRoot } = await loadRalphConfig()
await generateAll(config, projectRoot)

License

MIT