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

$3

``bash


Install from marketplace

/plugin add TheGlitchKing/aeon-loop

Start any project with one command:

/aeon-flux
`

$3

`bash


Install globally

npm install -g @theglitchking/aeon-loop

Run the installer

aeon-loop install --scope user

Check status

aeon-loop status

Or use npx (no install needed)

npx @theglitchking/aeon-loop install --scope user
`

Available commands:
- aeon-loop install - Install aeon-loop and bundled aeon-flux
- aeon-loop uninstall - Uninstall the plugins
- aeon-loop status - Check installation status
- aeon-loop help - Show help

Note: This package includes both aeon-loop and aeon-flux bundled together.

That's it. 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:

`bash


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

$3

| 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 |

$3

`
/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 COMPLETE is output: │
│ → Loop exits │
│ → Planning files remain for reference │
└─────────────────────────────────────────────────────────────┘
`

$3

task_plan.md (created automatically):
`markdown


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):
`markdown


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 |

$3

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

$3

| Option | Description | Default |
|--------|-------------|---------|
| --done | Completion promise to watch for | (required) |
| --max-iters | Maximum iterations before stopping | 100 |
| --workers | 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 COMPLETE │
│ - 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

$3

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

$3

`bash
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