loop-runtime

An open execution engine for AI agent loops. Loop Engineering teaches you how to design loops that prompt your agents. loop-runtime actually runs them — with a budget circuit-breaker, maker/checker sub-agents, worktree isolation, and human gates as first-class runtime primitives.

_{One real tick (mock backend, dry-run) — rendered from the actual CLI output by scripts/render_demo_gif.py.}

# zero install, no API key — runs the engine end-to-end with a mock backend
npx loop-runtime run daily-triage --level L2 --dry-run

Ran 1 tick(s) of Daily Triage [L2] via mock backend (dry-run):

  tick 1: act (accept) — 5000 tokens
           · triage decision: act
           · proposed change touching src/example.ts
           · verifier verdict: accept
           · committed: safe + allowlisted

Budget: 5,000 / 100,000 tokens spent today.

Why this exists

The loop-engineering ecosystem gives you the methodology and static tooling (loop-audit, loop-init, loop-cost) — all read-only or scaffolding. Nothing actually executes a loop. loop-runtime is that missing runtime. It consumes the same registry.yaml single source of truth, so it drops into an existing loop-engineering project with no new config.

flowchart LR
    A[Scheduler] --> B[Triage]
    B --> C{decision}
    C -->|noop / report| S[Write STATE + run-log]
    C -->|act| D[Worktree]
    D --> E[Implementer sub-agent]
    E --> F[Verifier sub-agent<br/>tests + gates]
    F -->|reject| X[Discard worktree]
    F -->|accept| G{Human gate}
    G -->|safe / allowlisted| I[Commit / PR]
    G -->|risky / denylisted| J[Escalate to human]
    I --> S
    J --> S
    S --> A
    B -.budget circuit-breaker.-> K[(Halt if over cap<br/>or kill-switch)]

Loading

Every box above is a real module — this is the loop-engineering "Anatomy of a Loop" diagram turned into running code.

How it's different from LangGraph / CrewAI / AutoGen

	Those frameworks	loop-runtime
Goal	build an agent app	operate a long-running, file-driven loop
Config	Python graphs / code	LOOP.md + registry.yaml (declarative)
Cost control	DIY	budget circuit-breaker + kill-switch built in
Safety	DIY	denylist/allowlist human gates + worktree isolation
Autonomy	all-or-nothing	phased L0→L3 enforced as a runtime guardrail
Verification	DIY	maker/checker split is the default execution shape

Install & use

# CLI
npx loop-runtime list                          # show patterns from registry.yaml
npx loop-runtime plan daily-triage --level L1  # resolve a runnable execution plan
npx loop-runtime run  ci-sweeper  --dry-run    # run tick(s) with the mock backend

As a library:

import { LoopEngine, buildPlan, BudgetBreaker, MemoryStateWriter, MockBackend } from 'loop-runtime';

const plan = buildPlan(pattern, { level: 'L2' });
const engine = new LoopEngine(plan, {
  backend: new MockBackend(),           // swap for the Claude Code backend
  state: new MemoryStateWriter(),
  budget: new BudgetBreaker(plan.dailyTokenCap),
});
const result = await engine.tick();     // structured, loggable TickResult

Architecture

Module	Responsibility
src/planner.ts	registry.yaml + level → ExecutionPlan (cadence, cap, action policy)
src/engine.ts	one loop tick: discover → triage → implement → verify → gate → commit/escalate
src/budget.ts	token circuit-breaker, daily roll-over, kill-switch
src/gates.ts	denylist/allowlist human-gate policy, max-attempt limits
src/state.ts	durable spine — writes STATE.md + appends loop-run-log.md
src/worktree.ts	git worktree isolation — throwaway branch per act-attempt, discarded on reject/escalate
src/backends/	pluggable AgentBackend — mock (deterministic) + claude (headless claude CLI)
src/yaml.ts	dependency-free registry reader (keeps npx install-free)

The engine layer is I/O-free: it operates on plain types and delegates all side effects (LLM calls, git, fs) to injected collaborators. That's why the whole loop is testable end-to-end with the deterministic mock backend and zero token spend.

Roadmap

• Phase 1 — Engine MVP: planner, scheduler-ready ticks, budget breaker, gates, mock backend, CLI
• Phase 2 — Isolation & real backend: git worktree isolation, Claude Code backend (--backend claude), --worktree flag
• Phase 2b — Visibility: local dashboard (cost burn-down, live loops, kill button)
• Phase 3 — Ecosystem: Codex/Grok backends, Slack/Discord notifiers, MCP connectors, GitHub Action distribution

See DESIGN.md for the full design.

Development

node --test test/*.test.ts   # zero-install: Node >= 23.6 runs TypeScript natively
npm test
npm run demo

License

MIT