Autoloop 0 4 0

autoloop 0.4.0

Overview

autoloop is a Node.js-based loop harness for long-running, multi-role agent workflows. It spins out the core ideas from ralph-orchestrator into something simpler and more opinionated: inspectable runs driven by reusable presets, event-based role routing with soft backpressure, an append-only JSONL journal as the canonical source of truth, and operator surfaces that both humans and agents can use directly.

The central idea is that long-running agent work improves dramatically when every iteration is recorded, workflows are declarative preset directories rather than code changes, and the system is designed for inspection — not just execution.

When to Use

• Building autonomous coding agents that iterate through plan → build → review → finalize cycles
• Needing quality gates between roles (e.g., critic must pass before completion)
• Running concurrent agent workflows without file conflicts (worktree isolation)
• Requiring persistent memory across loop runs (learnings, preferences, metadata)
• Composing multi-stage pipelines from reusable workflow presets (chains)
• Building operator dashboards or CLI surfaces for monitoring agent execution
• Designing agent systems where inspection matters as much as automation

Core Concepts

Presets are the product. Every workflow is a self-contained directory containing autoloops.toml (config), topology.toml (role graph), harness.md (shared instructions), and roles/*.md (per-role prompts). No code changes needed for new workflows.

Event-driven soft routing. Roles declare what events they can emit. A handoff map routes events to suggested next roles. The model receives advisory suggestions — it is not locked into a hard state machine. Backpressure at the event-emit boundary prevents protocol violations without forcing rigid transitions.

Append-only journal as canonical truth. Every lifecycle event, agent action, and coordination record is appended to .autoloop/journal.jsonl. Nothing is mutated or deleted. Higher-level views (scratchpad, metrics, coordination state) are projections derived from the journal.

Metareview hygiene loop. A periodic meta-level review pass runs between normal iterations to consolidate stale context, trim noisy working files, and store durable learnings — without directly advancing the task. It can hot-reload configuration mid-run.

Three orchestration layers. Topology handles intra-loop role routing. Chains compose inter-loop preset sequences. Dynamic chains allow a meta-orchestrator (an LLM agent) to plan and spawn new chain episodes at runtime with explicit budgets and lineage tracking.

Installation / Setup

npm install -g @mobrienv/autoloop

Or from source:

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

Requires Node.js >= 18.

Usage Examples

Start a coding loop with the bundled autocode preset:

autoloop run autocode "Fix the login bug"

Watch it in real time:

autoloop loops watch <run-id>

Inspect what happened after completion:

autoloop inspect journal <run-id>
autoloop inspect scratchpad --format md
autoloop inspect metrics --format csv

Run a multi-stage chain (code then QA):

autoloop run . --chain autocode,autoqa "Implement the approved change and validate it"

Keep implementation isolated in a git worktree with auto-merge:

autoloop run autocode --worktree --automerge "Implement the approved fix"

Open the local dashboard:

autoloop dashboard

Advanced Topics

Platform Architecture: Control plane, presets, journals, and external shells → Platform Architecture

Topology and Event Routing: Role definitions, handoff maps, soft routing with backpressure, design patterns → Topology and Event Routing

Journal System: Append-only JSONL lifecycle events, agent events, coordination events, scratchpad projections → Journal System

Memory and Tasks: Two-tier memory (project + run), materialization with tombstones, task completion gates → Memory and Tasks

Metareview Loop: Periodic hygiene reviews, hot-reload mid-run, context pressure management → Metareview Loop

Configuration Reference: autoloops.toml keys for event loop, backend, review, parallelism, worktree, memory → Configuration Reference

Worktree Isolation: Git-level isolation for concurrent runs, merge strategies, lifecycle management → Worktree Isolation

Chains and Dynamic Chains: Named chain compositions, runtime chain spawning with budgets and lineage → Chains and Dynamic Chains

Creating Custom Presets: Step-by-step preset authoring — topology, roles, harness, configuration → Creating Custom Presets

Bundled Preset Family: The auto* workflow taxonomy — autocode, autospec, autofix, autoqa, and more → Bundled Preset Family

CLI and Dashboard: Complete CLI subcommand reference and browser-based operator dashboard → CLI and Dashboard