@theglitchking/aeon-loop
v1.1.1
Published
Autonomous task execution with loop engine, orchestrated subagents, context persistence, and intelligent failure recovery. Includes bundled aeon-flux.
Maintainers
the-glitch-kingReadme
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
Via Claude Code Marketplace
# Install from marketplace
/plugin add TheGlitchKing/aeon-loop
# Start any project with one command:
/aeon-fluxVia NPM (Recommended for CLI users!)
# 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 userAvailable commands:
aeon-loop install- Install aeon-loop and bundled aeon-fluxaeon-loop uninstall- Uninstall the pluginsaeon-loop status- Check installation statusaeon-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:
# 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 analysisnotes.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 logPhilosophy
Based on the "Bash Loop" / "Ralphy Loop" approach:
- Action over explanation - Just do it, don't narrate
- Tight feedback loop - Observe → Act → Observe → Act
- Self-correction - Errors are feedback, fix immediately
- Persistent memory - Filesystem is external memory
- 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-loopManual
git clone https://github.com/TheGlitchKing/aeon-loop
cd aeon-loop
# Then in Claude Code:
/plugin install ./plugins/aeon-loopLicense
MIT
Credits
- Inspired by Ralph Loop by Geoffrey Huntley
- Built on Claude Code plugin system
- Incorporates Manus context engineering principles