@arcqdev/ralph-runner

Install

Use it as a local dependency for SDK or repo-level CLI usage:

vp add @arcqdev/ralph-runner

Or install the CLI globally:

npm i -g @arcqdev/ralph-runner

CLI Quick Start

Run a task directly:

ralph "Build feature x"

Pass context and a retry budget:

ralph --retries 3 --prompt "Vite+ monorepo, keep changes minimal" "Build feature x"

Or define a config file:

import { defineRalphRunnerConfig } from "@arcqdev/ralph-runner";

export default defineRalphRunnerConfig({
  task: "Build feature x",
  retries: 3,
  initialPrompt: "TypeScript package. Use Vite+ wrappers and keep the SDK coherent.",
  acpClient: {
    name: "codex",
    model: "gpt-5.4",
    fullAuto: true,
  },
  critique: {
    enabled: true,
    acpClient: {
      sandbox: "read-only",
      fullAuto: false,
    },
  },
});

Then run:

ralph

SDK Quick Start

import { runRalphRunner } from "@arcqdev/ralph-runner";

const result = await runRalphRunner({
  cwd: process.cwd(),
  task: "Build feature x",
  retries: 2,
  initialPrompt: "TypeScript package. Keep changes minimal and rerunnable.",
  acpClient: {
    name: "codex",
    model: "gpt-5.4",
    sandbox: "workspace-write",
  },
});

if (!result.completed) {
  throw new Error(`Task is still incomplete: ${result.reason}`);
}

For advanced integrations, the lower-level runner is still available:

import { createRunner } from "@arcqdev/ralph-runner";

const runner = createRunner({
  createClient: () => ({
    name: "stub",
    async executeTask() {
      return { summary: "stubbed task execution" };
    },
  }),
  createCritiqueJudge: () => async () => ({
    done: true,
    reason: "Stubbed critique marked the task complete.",
  }),
});

await runner.run({
  task: "Build feature x",
});

Register a Custom ACP Client

import {
  registerACPClient,
  runRalphRunner,
  type ACPClient,
  type ACPClientConfig,
} from "@arcqdev/ralph-runner";

registerACPClient(
  "internal-agent",
  (config?: ACPClientConfig): ACPClient => ({
    name: "internal-agent",
    async executeTask(context) {
      console.log("Executing", context.task, "with", config?.model ?? "default model");
      return { summary: "Applied internal-agent changes." };
    },
  }),
);

await runRalphRunner({
  task: "Build feature x",
  acpClient: {
    name: "internal-agent",
    model: "my-internal-model",
  },
});

CLI Flags

| Flag | What it does | | ---------------------- | ------------------------------------------------------- | | --task <text> | Explicit task prompt to run | | --retries <n> | Max follow-up attempts after the first task run | | --prompt <text> | Extra repo context for the implementation agent | | --cwd, --repo <path> | Target a different repo or working directory | | --client <name> | ACP client name, currently codex by default | | --model <name> | Model override for the ACP client | | --sandbox <mode> | read-only, workspace-write, or danger-full-access | | --verbose, -v | Stream ACP client logs during task attempts | | --config <path> | Explicit config file path |

How It Works

1. Run the implementation prompt through the configured ACP client.
2. Run a critique pass against the repository.
3. If critique says the task is done, stop successfully.
4. If critique says the task is not done, feed the critique feedback into the next ACP run.
5. Ralph Runner writes per-run artifacts under ~/.ralph-runner/runs/.

Package Exports

• @arcqdev/ralph-runner
• @arcqdev/ralph-runner/cli
• @arcqdev/ralph-runner/bin

Development

This repo uses Vite+.

./node_modules/.bin/vp check
./node_modules/.bin/vp test
./node_modules/.bin/vp run build

GitHub Pages is deployed from the committed docs/ directory through the workflow in .github/workflows/ci-pages.yml.

License

MIT