aeon-loop

Aeon Loop

/claude /plugin for Autonomous task execution for Claude Code. Start a task, walk away, return to find it complete.

Features Table

| Feature | ralph-loop | aeon-flux | mind-glaive | aeon-loop | |---------|-----------|-----------|-------------|-----------| | Loop engine | ✅ | - | - | ✅ | | Abort system | - | ✅ | - | ✅ | | Context persistence | - | partial | ✅ | ✅ | | Subagent coordination | - | ✅ | - | ✅ (enhanced) | | Pattern learning | - | - | ✅ | ✅ | | Attention preservation | - | ✅ | ✅ | ✅ | | Action philosophy | - | ✅ | - | ✅ | | Persistent planning | - | - | - | ✅ | | PRD generation | - | - | - | ✅ |

What Is This?

Aeon Loop is a Claude Code plugin that enables autonomous, multi-iteration task execution. It combines:

| Source Plugin | What It Contributes | |---------------|---------------------| | Ralph Loop | Autonomous iteration engine (Stop hook re-injects prompt) | | Aeon Flux | Abort system + "action over explanation" philosophy | | Mind Glaive | Context persistence across iterations and compactions | | Persistent Planning | Manus-style persistent markdown planning |

Quick Start

> v1 → v2 breaking change: the hand-rolled aeon-loop install --scope user flow was removed. Installation is now handled automatically by either the Claude Code plugin marketplace or npm's postinstall. See CHANGELOG.md for migration details.

Option A: Claude Code Plugin Marketplace (Recommended)

/plugin marketplace add TheGlitchKing/aeon-loop
/plugin install aeon-loop@aeon-loop-marketplace
/aeon-flux

Option B: Project-level npm install

Pins the version in package.json, visible to teammates, CI, and LLMs reading the repo.

npm install --save-dev @theglitchking/aeon-loop

Postinstall writes .claude/aeon-loop.json (update policy: nudge) and registers a SessionStart update-check hook in .claude/settings.json (skipped if the marketplace plugin is already enabled in ~/.claude/settings.json).

Update management

Every install ships with an update policy. Default is nudge — one-liner notification at session start when a newer version is available, no automatic changes.

aeon-loop status          # installed / latest / policy / hook state
aeon-loop policy auto     # auto-update on session start
aeon-loop policy nudge    # one-liner nudge only (default)
aeon-loop policy off      # silent
aeon-loop update          # update now

Slash-command parity: /aeon-loop:status, /aeon-loop:policy <mode>, /aeon-loop:update, /aeon-loop:relink.

Note: This package includes both aeon-loop and aeon-flux bundled together. The unified workflow guides you through everything.

The Workflow

When you run /aeon-flux, you'll be guided through a complete project lifecycle:

/aeon-flux
    │
    ▼
┌─────────────────────────────────────────────────────────────┐
│ PHASE 0: EXPLORATION (Optional)                             │
│                                                             │
│ "I see this is an existing project.                        │
│  Would you like me to explore the codebase first?"         │
│                                                             │
│ 1.1. Full analysis (structure, patterns, architecture)     │
│ 1.2. Quick overview                                        │
│ 2.1. Skip - I'm familiar with this codebase               │
│ 2.2. Skip - This is a new project                          │
│                                                             │
│ → Launches parallel agents to explore                      │
│ → Saves report to .planning/exploration/report.md          │
└─────────────────────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────────────────────────┐
│ PHASE 1: DISCOVERY                                          │
│                                                             │
│ "What would you like to build?"                            │
│                                                             │
│ → Asks 3-5 clarifying questions with numbered options      │
│ → You respond: "1.1, 2.2, 3.1"                             │
│ → Continues until 90% confident                            │
└─────────────────────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────────────────────────┐
│ PHASE 2: PRD CREATION                                       │
│                                                             │
│ → Generates Product Requirements Document                   │
│ → Right-sized user stories (completable in one iteration)  │
│ → Saves to .planning/[task-slug]/prd.md                    │
│                                                             │
│ "Does this PRD capture what you want?"                     │
└─────────────────────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────────────────────────┐
│ PHASE 3: PLANNING                                           │
│                                                             │
│ → Creates implementation plan from PRD                      │
│ → Groups stories into phases                                │
│ → Saves to .planning/[task-slug]/task_plan.md              │
│                                                             │
│ "Here's the plan. Ready to start?"                         │
└─────────────────────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────────────────────────┐
│ PHASE 4: EXECUTION MODE                                     │
│                                                             │
│ "How would you like to proceed?"                           │
│                                                             │
│ A) Set it and forget it (Recommended)                      │
│    → Autonomous execution until complete                    │
│    → Check /status anytime                                  │
│    → Use /abort if needed                                   │
│                                                             │
│ B) Be in the loop                                           │
│    → Collaborative, checks in after each story              │
│    → You guide decisions as you go                          │
└─────────────────────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────────────────────────┐
│ PHASE 5: IMPLEMENTATION                                     │
│                                                             │
│ → Works through stories in dependency order                 │
│ → Updates progress in STATE blocks                          │
│ → Continues until all stories complete                      │
│ → Verifies all STATE blocks show passes: true               │
└─────────────────────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────────────────────────┐
│ PHASE 6: COMPREHENSIVE TESTING                              │
│                                                             │
│ → Only proceeds if all stories are complete                 │
│ → Detects test framework (jest, pytest, go test, etc.)     │
│ → Creates missing tests for new functionality               │
│ → Runs full test suite                                      │
│ → Fixes any failing tests                                   │
│ → Verifies all tests pass before proceeding                 │
└─────────────────────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────────────────────────┐
│ PHASE 7: VERIFICATION                                       │
│                                                             │
│ → Re-reads original PRD                                     │
│ → Verifies all requirements met                             │
│ → If something was missed, creates follow-up plan           │
│                                                             │
│ "All requirements implemented. Project complete!"           │
└─────────────────────────────────────────────────────────────┘

Individual Commands

You can also use individual commands if you prefer granular control:

# Explore codebase only
/explore

# Create PRD only
/prd "Feature description"

# Create planning structure only
/start-planning "Task name"

# Start autonomous execution directly
/loop "Task description" --done "COMPLETE"

Planning System

Aeon Loop uses persistent markdown files as working memory. Unlike in-memory todo lists, these files:

• Persist forever on disk (until you delete them)
• Survive context compaction and session restarts
• Guide every iteration of the loop
• Can be edited while paused to modify the plan

Two Layers of Files

| Layer | Location | Purpose | Lifecycle | |-------|----------|---------|-----------| | Planning | .planning/[task]/ | Define WHAT to do | Created once, updated during work | | Runtime | .claude/ | Track HOW it's going | Created by /loop, updated each iteration |

How Planning Files Are Used

/loop "Build API" --done "COMPLETE"
         │
         ▼
┌─────────────────────────────────────────────────────────────┐
│ SETUP (once)                                                │
│ Creates .planning/build-api/task_plan.md (if not exists)   │
│ Creates .claude/loop-state.md                              │
│ Creates .claude/memory/checkpoint.md                       │
└─────────────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────────┐
│ EACH ITERATION                                              │
│                                                             │
│ SessionStart hook loads:                                    │
│   → .claude/memory/checkpoint.md (where we left off)       │
│   → .claude/memory/attention.md (critical context)         │
│   → .planning/build-api/task_plan.md (phases, goals)       │
│                                                             │
│ Claude works on the task, guided by task_plan.md           │
│                                                             │
│ Stop hook:                                                  │
│   → Saves progress to checkpoint.md                        │
│   → Updates task_plan.md status                            │
│   → Re-injects prompt for next iteration                   │
└─────────────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────────┐
│ COMPLETION                                                  │
│ When <promise>COMPLETE</promise> is output:                │
│   → Loop exits                                              │
│   → Planning files remain for reference                    │
└─────────────────────────────────────────────────────────────┘

Planning File Templates

task_plan.md (created automatically):

# Task Plan: Build API

## Goal
Build a REST API with JWT auth

## Phases
- [ ] Phase 1: Analyze requirements and plan approach
- [ ] Phase 2: Implement core functionality
- [ ] Phase 3: Test and validate
- [ ] Phase 4: Review and complete

## Key Questions
1. What are the main components needed?
2. What dependencies exist?

## Decisions Made
- (updated during execution)

## Errors Encountered
- (auto-captured by hooks)

## Status
**Currently in Phase 1** - Starting analysis

notes.md (for research and findings):

# Notes: Build API

## Key Findings
- (discoveries during work)

## Research Sources
- (references used)

Commands

| Command | Description | Example | |---------|-------------|---------| | /aeon-flux | Unified workflow - Explore → PRD → Plan → Execute | /aeon-flux | | /explore | Explore codebase with parallel agents | /explore or /explore "auth system" | | /prd | Generate a Product Requirements Document | /prd "User authentication" | | /start-planning | Create planning structure only | /start-planning "Build API" | | /loop | Start autonomous execution | /loop "Build API" --done "DONE" | | /abort | Stop all agents immediately | /abort or /abort clear | | /status | Show progress | /status | | /pause | Pause after current iteration | /pause | | /resume | Continue paused loop | /resume | | /retry | Retry a failed chunk | /retry chunk-003 | | /checkpoint | Force save current state | /checkpoint |

/start-planning vs /loop

| Command | Creates Planning Files | Starts Loop | Use When | |---------|----------------------|-------------|----------| | /start-planning | ✅ | ❌ | Want to customize plan first | | /loop | ✅ (if needed) | ✅ | Ready to execute immediately |

/loop Options

| Option | Description | Default | |--------|-------------|---------| | --done <text> | Completion promise to watch for | (required) | | --max-iters <n> | Maximum iterations before stopping | 100 | | --workers <n> | Max concurrent workers for complex tasks | 3 | | --quiet | Minimal output between iterations | false |

How It Works

/loop "Your task" --done "COMPLETE"
         │
         ▼
┌────────────────────────────────────────┐
│ ITERATION 1                            │
│ - Load context from memory files       │
│ - Read task_plan.md for guidance       │
│ - Work on task                         │
│ - Update task_plan.md status           │
│ - Try to exit                          │
│ - Stop hook blocks, saves checkpoint   │
│ - Re-injects prompt                    │
└────────────────────────────────────────┘
         │
         ▼
┌────────────────────────────────────────┐
│ ITERATION 2                            │
│ - Load checkpoint                      │
│ - Read updated task_plan.md            │
│ - Continue from where left off         │
│ - Make more progress                   │
│ - ...                                  │
└────────────────────────────────────────┘
         │
         ▼
    (repeats until...)
         │
         ▼
┌────────────────────────────────────────┐
│ COMPLETION                             │
│ - Output <promise>COMPLETE</promise>   │
│ - task_plan.md marked complete         │
│ - Stop hook allows exit                │
│ - Task done!                           │
└────────────────────────────────────────┘

Examples

See the examples/ folder for detailed usage guides:

| Example | Description | |---------|-------------| | Simple Feature | Basic /loop usage with /start-planning | | Bug Fix with Tests | Fixing bugs with verification | | Large Refactoring | Multi-file changes with orchestration | | API Development | Building new features | | Using /abort | Stopping and resuming | | Using /status | Monitoring progress | | Using /pause & /resume | Graceful pausing | | Using /retry | Retrying failed chunks |

Safety Limits

| Limit | Value | Purpose | |-------|-------|---------| | MAX_CONCURRENT_WORKERS | 3 | API rate limits, debuggability | | MAX_TOTAL_WORKERS | 50 | Prevent runaway spawning | | MAX_RETRIES_PER_CHUNK | 3 | Then escalate | | MAX_CONSECUTIVE_FAILURES | 5 | Circuit breaker trips | | WORKER_TIMEOUT | 10 min | Kill stalled workers | | HEARTBEAT_STALE | 90 sec | Detect dead workers |

File Structure

project/
├── .planning/[task-slug]/          # PLANNING LAYER
│   ├── prd.md                      # Product Requirements Document (from /prd)
│   ├── task_plan.md                # Phases, decisions, status
│   └── notes.md                    # Research and findings
│
└── .claude/                        # RUNTIME LAYER
    ├── loop-state.md               # Iteration tracking
    ├── orchestration/              # Chunk breakdown (complex tasks)
    │   ├── manifest.md
    │   └── chunks/
    └── memory/
        ├── checkpoint.md           # Progress snapshot
        ├── attention.md            # Critical context
        ├── patterns.md             # Learned corrections
        └── errors.md               # Error log

Philosophy

Based on the "Bash Loop" / "Ralphy Loop" approach:

1. Action over explanation - Just do it, don't narrate 2. Tight feedback loop - Observe → Act → Observe → Act 3. Self-correction - Errors are feedback, fix immediately 4. Persistent memory - Filesystem is external memory 5. Attention manipulation - Re-read goals to keep them in focus

Requirements

• Claude Code 2.0.13+
• Bash shell
• jq (for JSON parsing in hooks)

Installation

From Marketplace (Recommended)

/plugin
→ Add Marketplace
→ TheGlitchKing/aeon-loop
→ Install aeon-loop

Manual

git clone https://github.com/TheGlitchKing/aeon-loop
cd aeon-loop
# Then in Claude Code:
/plugin install ./plugins/aeon-loop

License

MIT

Credits

• Inspired by Ralph Loop by Geoffrey Huntley
• Built on Claude Code plugin system
• Incorporates Manus context engineering principles