Athena Loops

Athena Loops (the agentloop package) is a lightweight Python framework for multi-agent orchestration. It implements the orchestrator → worker → reviewer pattern as a deterministic harness with a closed feedback loop: a goal is decomposed into subtasks, fanned out to worker subagents, aggregated, and run through a review gate that loops until the work meets its success criteria.

The design principle

The loop is a harness (deterministic code), not a skill. A prompt can describe “decompose, review, loop until done” but can’t guarantee it. So the control flow lives in code, and the model-facing judgement — how to decompose, the review rubric — lives in swappable prompts.

            ┌──────────── harness (agentloop) ───────────────┐
goal ─▶ decompose ─▶ fan-out to subagents ─▶ aggregate ─▶ review gate ─▶ done?
            ▲                                                          │ no
            └──────────────── feedback: refine plan ◀──────────────────┘

Backend-agnostic by design

One loop drives whichever backend you bring, through a single Agent interface:

API backends: Anthropic Claude, or Grok via xAI’s OpenAI-compatible API.
Coding-agent CLIs as workers: CliAgent presets for Claude Code, Codex, opencode, aider, and Grok Build run each role through a headless coding-agent CLI, so workers get that agent’s tools, file access, and repo context. Auth piggybacks on the CLI’s own login — no provider API key needed.
Custom CLIs: any command template with {prompt} / {system} placeholders.

Safety and recoverability

Isolated runs: when pointed at a repo, the loop runs inside a throwaway git worktree on its own branch by default — your main checkout is never touched.
Checkpoint commits: the worktree is committed after every iteration, so partial work survives a failed run or a budget stop.
Real verification: verify_commands runs deterministic checks (pytest, npm test, …) after each iteration; a failing verifier blocks completion even if the reviewer would accept the work.
Budgets: iteration and wall-clock budgets are enforced by the harness, between iterations.

Two ways to plug it in

Inward — coding agents are the workers: construct an Orchestrator around a CliAgent in Python.
Outward — a coding agent calls the loop: Athena Loops ships as an MCP server, so any MCP-aware agent (Claude Code, Cursor, Codex, opencode, Cline, Windsurf) can invoke orchestrate(...) as a tool, monitor a detached run, and read back a structured result.

See Getting Started for installation, the Python quick start, and the MCP server.