Installation

ralphmania runs on Deno v2. No install required — run directly from JSR:

deno run -A jsr:@cdaringe/ralphmania -i 10

Or cache it for repeated use:

deno install -Ag -n ralphmania jsr:@cdaringe/ralphmania ralphmania -i 10

Write a Specification

Create a specification.md in your project root. Each row in a markdown table is one scenario the AI will tackle:

# My Project Specification

| # | Category | Description |
| - | -------- | ----------- |
| 1 | Setup    | Initialise the project with a deno.json and README |
| 2 | API      | Create a REST endpoint GET /health that returns 200 |
| 3 | Tests    | Write tests for the health endpoint |
| 4 | CI       | Add a GitHub Actions workflow that runs tests |

Running the Tool

From your project directory, run with the desired iteration count:

# Run up to 10 agent iterations
deno run -A jsr:@cdaringe/ralphmania -i 10

# Use a specific AI agent (default: claude)
deno run -A jsr:@cdaringe/ralphmania -i 10 --agent claude

# Load a plugin
deno run -A jsr:@cdaringe/ralphmania -i 10 --plugin ./plugin.ralph.ts

# Reset all worktrees before starting
deno run -A jsr:@cdaringe/ralphmania -i 10 --reset-worktrees

Reading Progress

ralphmania writes a progress.md file tracking every scenario:

# Progress

| # | Status        | Summary                     | Rework Notes |
| - | ------------- | --------------------------- | ------------ |
| 1 | VERIFIED      | Created deno.json + README  |              |
| 2 | WORK_COMPLETE | Health endpoint added       |              |
| 3 | WIP           |                             |              |
| 4 | WIP           |                             |              |

Possible statuses:

• WIP — work in progress, not yet submitted
• WORK_COMPLETE — agent finished, awaiting validation
• VERIFIED — passed validation, scenario done
• NEEDS_REWORK — validation failed, will be retried
• OBSOLETE — scenario removed from spec

Configuring via Plugins

Plugins are TypeScript files that export hooks. Create a plugin.ralph.ts:

import type { Plugin } from "jsr:@cdaringe/ralphmania";

export const plugin: Plugin = {
  onPromptBuilt({ prompt }) {
    return prompt + "\nAlways add JSDoc comments to exported functions.";
  },
  onValidationComplete({ result }) {
    if (!result.passed) {
      console.log("Validation failed:", result.messages);
    }
    return result;
  },
};

See the Reference page for the full list of plugin hooks.