Getting Started

Quick start

The core loop has no required dependencies — clone and run the demo with a mock agent:

git clone https://github.com/luckeyfaraday/athena-loops.git
cd athena-loops
python3 -m examples.run_demo        # zero-dependency MockAgent
python3 -m pytest                   # full test suite, no deps

from agentloop import Orchestrator, Budget
from agentloop.adapters import MockAgent

orch = Orchestrator(MockAgent(), budget=Budget(max_iterations=4))
result = orch.run(
    goal="Write a briefing on the orchestrator-worker pattern.",
    success_criteria="Covers decomposition, execution, review, and the feedback loop.",
)
print(result.completed, result.iterations, result.stop_reason)
print(result.final_output)

Use a real model

Claude via the Anthropic API:

pip install -e ".[claude]"
export ANTHROPIC_API_KEY=sk-...
python3 -m examples.run_demo --claude

Coding agents as workers

CliAgent runs each role (decomposer / subagent / reviewer) through a headless coding-agent CLI:

from agentloop import Orchestrator
from agentloop.adapters import CliAgent

agent = CliAgent.claude_code(cwd="/path/to/repo", skip_permissions=True)
orch = Orchestrator(agent)          # or .codex() / .opencode() / .aider()
result = orch.run(goal="Add a /health endpoint + test", success_criteria="test passes")

Useful knobs:

cwd=... — run the worker inside a specific repo.
skip_permissions=True — headless tool use without prompting. This bypasses the agent’s safety prompts, so point it at a worktree or throwaway branch, not your main checkout.
verify_commands=[...] — deterministic post-iteration checks (python3 -m pytest, npm test, …) whose failures feed back into the next loop.
Budget(max_iterations=..., max_seconds=...) — bound the run, not each call.

Isolated runs

The safe default for skip_permissions is a throwaway git worktree on its own branch:

from agentloop import Orchestrator, worktree
from agentloop.adapters import CliAgent

with worktree("/path/to/repo") as wt:               # new branch + checkout
    agent = CliAgent.claude_code(cwd=wt.path, skip_permissions=True)
    Orchestrator(agent).run(goal="...", success_criteria="...")
    print(wt.changed_files())
    wt.commit("agentloop run")      # optional: persist on the branch

The loop commits the worktree after every iteration (agentloop: iteration N), so partial work is preserved as checkpoint commits even if a later iteration fails.

The MCP server

Expose the loop as a tool for any MCP-aware agent:

pip install -e ".[mcp]"
python3 -m agentloop.mcp_server        # stdio transport

Key tools:

Tool	What it does
`orchestrate(goal, success_criteria, …)`	Starts the loop. Detached by default: returns `{ status: "running", run_id, … }` immediately.
`orchestrate_status(run_id)`	Light status of a detached run (phase, iteration, running).
`orchestrate_tail(run_id, cursor)`	Events the run produced since `cursor`.
`orchestrate_result(run_id)`	The final structured result, once the run stops.
`orchestrate_resume(token, answers)`	Continues a run that asked for input.
`list_backends()` / `doctor(cwd?)`	Which worker engines are available; non-invasive diagnostics.

With backend="auto" (the default) the server uses the same agent family as the caller when detectable; pass backend explicitly to override.