@mobrienv/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

Install

From npm (recommended)

npm install -g @mobrienv/autoloop

Standalone binary (no Node required)

npm remains the primary and recommended installation channel. For a Node-free installation, download the binary for your OS and architecture plus SHA256SUMS from the GitHub release:

VERSION=v0.10.1
TARGET=darwin-arm64 # darwin-arm64, darwin-x64, linux-arm64, or linux-x64
curl -LO "https://github.com/mikeyobrien/autoloop/releases/download/${VERSION}/autoloop-${TARGET}"
curl -LO "https://github.com/mikeyobrien/autoloop/releases/download/${VERSION}/SHA256SUMS"
grep "  autoloop-${TARGET}$" SHA256SUMS > SHA256SUMS.current
sha256sum -c SHA256SUMS.current # Linux
# shasum -a 256 -c SHA256SUMS.current # macOS
chmod +x "autoloop-${TARGET}"
sudo mv "autoloop-${TARGET}" /usr/local/bin/autoloop

From source

git clone https://github.com/mikeyobrien/autoloop.git && cd autoloop
npm install
npm run build
node bin/autoloop --help

Quick start

# Run a bundled preset
autoloop run autocode "Fix the login bug"

# Inspect active and recent runs
autoloop loops

# Open the local dashboard
autoloop dashboard

# Keep an implementation pass isolated in a git worktree
autoloop run autocode --worktree --automerge "Implement the approved fix"

autocode is a bundled preset. The quoted string is the objective passed to the loop.

The usual golden path is:

• start a loop with a preset
• watch it move through iterations
• inspect the journal, events, and artifacts
• open the dashboard when you want a higher-level operator view
• use worktree isolation when the loop is making risky repo changes

Usage

The main commands are:

autoloop run <preset-name|preset-dir> [prompt...] [flags]
autoloop init [--preset <name>] [dir]
autoloop list [--json]
autoloop loops [--all] [--json]
autoloop loops show <run-id> [--json]
autoloop loops artifacts <run-id> [--json]
autoloop loops watch <run-id>
autoloop loops health [--verbose] [--json]
autoloop inspect <artifact> [selector] [project-dir] [--format <md|terminal|text|json|csv|graph>]
autoloop dashboard [--port <port>]
autoloop worktree <list|show|diff|merge|clean> [args]
autoloop chain list [project-dir]
autoloop chain run <name> [project-dir] [prompt...] [--dry-run] [--json]
autoloop emit <topic> [summary]
autoloop memory <list|status|find|add|remove|compact|prune> [args]
autoloop task <add|complete|update|remove|list> [args]
autoloop runs clean [--max-age <days>]
autoloop stats [project-dir] [--json]
autoloop doctor [project-dir] [--json]
autoloop triage [project-dir] [--json]
autoloop config <show|set|unset|path> [args]
autoloop capabilities
autoloop robot-docs
autoloop --version

Use run to start work, loops and inspect to understand what happened, and dashboard when you want a local operator surface. stats summarizes success rates and cost per preset; doctor diagnoses the environment and .autoloop state. triage is the one-call status command for agents — runs, health, doctor, and recommended next commands in a single (optionally --json) invocation. capabilities prints the machine-readable CLI contract (commands, JSON surfaces, exit codes) and robot-docs prints a paste-ready agent handbook.

Errors always go to stderr with a documented exit code (0 success, 1 user-input error, 2 environment error), and mistyped commands, subcommands, and flags get a "Did you mean" correction instead of being misinterpreted.

Flags

Flag	Description
-h, --help	Show usage
-v, --verbose	Debug-level logging
-b, --backend	Override backend (e.g. -b claude-sdk, -b pi, -b kiro, or a command)
-p, --preset	Resolve a named or custom preset
--chain	Run an inline chain of comma-separated presets
--profile <spec>	Activate a profile (repo:<name> or user:<name>), repeatable
--no-default-profiles	Suppress config-defined default profiles

Examples

# Run a preset against a coding task
autoloop run autocode "Refactor the auth module"

# Run a QA pass
autoloop run autoqa "Exercise the new onboarding flow and report UX issues"

# Run from a custom preset directory
autoloop run ./my-preset "Analyze the API"

# Keep implementation isolated in a worktree
autoloop run autocode --worktree --automerge "Implement the approved fix"

# Watch a run in progress
autoloop loops watch <run-id>

# Inspect what happened after the run completes
autoloop inspect journal <run-id>
autoloop loops artifacts <run-id>

# Open the dashboard
autoloop dashboard

# Run an inline chain
autoloop run --chain autospec,autocode "Design and build feature X"

Bundled presets

Bundled presets give you opinionated starting points for common workflows like coding, QA, docs, review, security, specs, and performance.

Preset	Purpose
autocode	Plan, build, review, and commit code changes
autosimplify	Scope, simplify, verify, and review code for simplicity
autoideas	Scan, analyze, review, and synthesize improvement ideas
autoresearch	Research strategies, implement, evaluate, and benchmark
autoqa	Plan, execute, inspect, and report on QA
autotest	Survey, write, run, and assess tests
autofix	Diagnose, fix, and verify bugs
autoreview	Read, suggest, check, and summarize code reviews
autodoc	Audit, write, verify, and publish documentation
autosec	Scan, analyze, harden, and report on security
autoperf	Profile, measure, optimize, and judge performance
autospec	Research, clarify, design, plan, and critique specifications
automerge	Merge a completed worktree branch back into its base branch
autopr	Turn the current branch into a reviewable pull request
autowiki	Ingest a queue of source URLs into an OKF-conformant LLM wiki of cross-linked concept pages

Creating custom presets

A preset is a directory containing autoloops.toml, topology.toml, harness.md, and a roles/ folder. See Creating presets for the full guide, or examine any presets/<name>/ directory as a working example.

Some older or internal layouts may still include miniloops.toml, but autoloops.toml is the canonical entry point for new presets.

Project structure

autoloop/
├── bin/autoloop        # CLI entry point (Node.js ESM)
├── src/                # TypeScript source
│   ├── main.ts         # CLI dispatch
│   ├── harness/        # Loop engine (iteration, events, routing)
│   ├── config.ts       # TOML config loading
│   ├── chains.ts       # Chain orchestration
│   ├── memory.ts       # Persistent loop memory
│   └── usage.ts        # Help text
├── presets/            # Bundled preset definitions
│   └── <name>/
│       ├── autoloops.toml
│       ├── topology.toml
│       ├── harness.md
│       └── roles/
├── docs/               # Reference documentation
├── dist/               # Compiled output (generated)
└── package.json

Developer scripts

A convenience dispatcher lives at bin/dev:

bin/dev build          # compile TypeScript
bin/dev test           # run the test suite
bin/dev test:watch     # vitest in watch mode
bin/dev hooks          # install git hooks
bin/dev run [args]     # run autoloop
bin/dev --help         # list all subcommands

Running tests

npm test

Runs the test suite via Vitest.

Mock backend

A deterministic mock backend (src/testing/mock-backend.ts) removes the need for a live LLM during testing. Point it at a JSON fixture to control output, exit code, and emitted events:

export MOCK_FIXTURE_PATH=test/fixtures/backend/complete-success.json
node bin/autoloop run . -b "node dist/testing/mock-backend.js"

See CLI reference for fixture schema and bundled scenarios.

Further reading

• Platform architecture
• Configuration reference
• Creating presets
• Topology and event routing
• Memory system
• Dynamic chains
• CLI reference
• Dashboard
• Profiles
• Tasks
• Worktree isolation
• Releasing

Local CI / merge gate

No GitHub Actions on PRs. Prove green locally, then sign off. Full pattern: docs/ci-local.md.

npm ci
npm run build
npm run check          # biome + tsc --noEmit + vitest coverage

gh extension install basecamp/gh-signoff
gh signoff             # posts context `signoff` — required to merge

Publish and docs deploy still run on tags / main (publish-npm.yml, docs.yml). Do not add a PR ci.yml back.

Contributing

Bug reports and pull requests are welcome at github.com/mikeyobrien/autoloop.

Prerequisites for development: Node.js >= 18, npm. Run npm install && npm run build to get started, then npm run check to verify. Merge requires local proof plus gh signoff (see docs/ci-local.md).