agent-loop

agent-loop

Give an AI agent a one-line goal. It runs an autonomous loop that works toward it, verifies its own output, journals, and fires its own next tick — AI-first, token-light, self-evolving.

Self-evolving autonomous loops for AI coding agents (Claude Code & Codex). You set direction; the loop runs itself — observe → act → verify → journal → re-evolve its next directive, with no user in the inner loop. The engine is plain Python + JSON + markdown instructions: no API key, no build step, no infra — it rides whichever agent you already use. (~1.4k always-on tokens for all 11 skills; the heavy thinking is pay-per-use.)

The one idea

A tick is a pure function:

(state.json + new data) → (action + new state + one log record)

Each tick is a stateless agent. The substrate (state.json + log.jsonl) is the loop's entire memory between ticks, so token cost per tick is bounded no matter how long history grows. The loop "evolves" because every tick rewrites state.next — the directive the next tick reads first.

Only one thing changes by type of work — a profile. The loop primitive and substrate are identical for all:

Profile	For	Gate ("what good means")
research	investigate an open question	every claim triangulated across ≥2 independent sources, refuted, cited, confidence-scored
experiment	validate an idea vs a slow/noisy signal	pre-registered bar, frozen before peeking; honest null = success
build	construct from a milestone DAG	acceptance met and a verifier separate from the builder confirms
maintenance	keep an existing app healthy	full suite green before and after; no regression; surgical edits

Install (Claude Code plugin)

/plugin marketplace add AndonMitev/agent-loop
/plugin install agent-loop@agent-loop

Then in any project: /spawn-loop "<your goal>". On first run the helper is copied into that project's .loop/.

Quickstart (install → first output)

/plugin marketplace add AndonMitev/agent-loop
/plugin install agent-loop@agent-loop
/spawn-loop "keep this repo green and tidy"

/spawn-loop classifies the goal, seeds .loop/<id>/, runs the first tick, and schedules the next — you don't click through iterations. You'll see a loop appear:

$ python3 .loop/loop.py list
repo-health  [maintenance] event    cyc=  1  preg=0 todo=0  next: sleep until a health signal fires …

Inspect it with python3 .loop/loop.py status repo-health; remove it with python3 .loop/loop.py rm repo-health.

Use — a full walkthrough (real commands, real output)

# 1. Spawn. One command: classifies the goal, seeds .loop/, runs the first tick, schedules the next.
/spawn-loop "keep my repo green: tests pass and types check"
#   → creates loop 'repo-green' [maintenance], runs tick 1, self-schedules

# 2. See all your loops.
python3 .loop/loop.py list
#   repo-green  [maintenance] event  cyc=1  preg=0 todo=0  next: sleep until a health signal fires …

# 3. Inspect one loop — goal, gate, last reading, what it'll do next.
python3 .loop/loop.py status repo-green

# 4. Nudge it manually (it ticks itself; use this only to debug or push it along).
/loop-tick repo-green

# 5. Delete it when you're done.
python3 .loop/loop.py rm repo-green

More worked examples — one per profile (research / experiment / build / maintenance) — in EXAMPLES.md.

Autonomy (AI-first)

The loop does not rely on you to drive each step — you give a goal and approve hard gates; it does the rest. It is built to behave like an autonomous engineer, not a script. Every tick lives by a Prime directive (the first thing loop-tick reads, overriding everything else):

1. Decide + act, never passive. A tick never ends on a wait or a status report — it changes state/code/config, records a verdict, or makes an explicit, justified no-op. It always moves toward the goal.
2. Invoke skills, don't describe them. When the work calls for a capability (/deep-research, /grill-ai, /plan-decompose, /test-driven-development, …) the loop calls the skill — judgment-gated (only when it earns its tokens), never paraphrased or simulated.
3. Grill itself at every real distinction. Any kill/keep, promote, tombstone, anomaly, or surprising result fires /grill-ai adversarial self-critique before the call is committed. The loop argues with itself so you don't have to.