autoloop

autoloop

autoloop is a spinoff of ralph-orchestrator built to keep the parts that mattered and drop a lot of the extra experimental surface area.

It’s a simpler, more opinionated loop harness for long-running agent work: inspectable runs, easier preset-driven workflows, and operator surfaces that agents can use directly too.

It’s early and still evolving. autoloop is not a replacement for ralph-orchestrator — it’s a cleaner path for exploring a simpler UX without breaking Ralph.

Read the docs →

Use as a library

As of 0.5.0-sdk.0, autoloop ships an embed-able runtime alongside the CLI. Pass an AbortSignal for cancellation and an onEvent callback to consume the structured event stream — no terminal output is produced unless you ask for it.

import { run, type LoopEvent } from "@mobrienv/autoloop";

const controller = new AbortController();
setTimeout(() => controller.abort(), 60_000);

const summary = await run("./my-project", "build the login page", "autoloop", {
  signal: controller.signal,
  onEvent: (event: LoopEvent) => {
    if (event.type === "iteration.start") console.log(`iter ${event.iteration}`);
    if (event.type === "loop.finish") console.log(`done: ${event.stopReason}`);
  },
});

console.log(summary); // { iterations, stopReason, runId }

The CLI entry (bin/autoloop) is still the primary interface; the library export is for agent frameworks and dashboards that want to drive loops in-process.

Why autoloop exists

ralph-orchestrator grew to include a lot of different experiments and ways of doing things. autoloop spins out a narrower set of ideas into something simpler and more opinionated.

The bet is that long-running agent workflows get much better when they are:

• inspectable after every iteration
• easy to launch through reusable presets
• safe to run in isolation when they touch real code
• operable by both humans and agents

If Ralph is the broader experimentation surface, autoloop is the cleaner runtime path.

What it emphasizes

• Inspectable long-running loops -- every iteration is recorded in an append-only journal, with tools to inspect prompts, outputs, topology, metrics, tasks, memory, and artifacts
• Easier preset-driven workflows -- bundled presets give you a fast starting point, and custom preset creation is a first-class path
• Operator visibility -- loops, watch, health, inspect, and the local dashboard show what actually happened
• Worktree isolation + automerge -- run risky coding passes in git worktrees and merge them back only when ready
• Designed for agents too -- autoloop is intentionally shaped as a surface that agents can use directly, not just a human operator CLI
• Dynamic chains -- compose presets into multi-stage pipelines
• Persistent memory + profiles -- loops accumulate learnings across runs and can load repo/user tuning profiles
• Cost budgets + stall protection -- stop runaway loops automatically with event_loop.max_cost_usd (journaled token cost) and event_loop.stall_iterations (repeated identical outputs)
• Runtime budgets -- bound wall-clock time with event_loop.max_runtime (whole loop) and event_loop.max_iteration_runtime (per iteration, for iterations that wait days on long-running workflows); both take "3d"/"12h"-style durations
• Finish notifications -- run any command when a loop ends ([notify] command = "...") with run metadata in env vars and a JSON payload on stdin

What autoloop is

• a simpler, more opinionated spinoff of ralph-orchestrator
• a loop harness for long-running agent workflows
• a system built around inspectability, presets, and operator visibility
• a tool for both human operators and agents

What it is not

• not a replacement for ralph-orchestrator
• not just a thin CLI wrapper around model calls
• not a generic workflow engine for everything
• not optimized for the broadest possible feature surface

Table of contents

• Why autoloop exists
• What it emphasizes
• What autoloop is
• What it is not
• Install
• Quick start
• Usage
• Bundled presets
• Creating custom presets
• Project structure
• Developer scripts
• Running tests
• Further reading
• Contributing