{
  "markdown": "# Aeon Flux\n\nA Claude Code plugin that makes Claude **faster, smarter, and more reliable** by implementing the Bash Loop architecture.\n\n> Inspired by Geoffrey Huntley's \"Ralphy Loop\" - enhanced with solutions for its known limitations.\n\n---\n\n## What Does This Do?\n\nAeon Flux changes how Claude Code behaves:\n\n| Before (Default Claude) | After (Aeon Flux) |\n|------------------------|-------------------|\n| \"Let me explain what I'm going to do...\" | *Just does it* |\n| \"I apologize for the error...\" | *Fixes it silently* |\n| \"Here's a summary of the output...\" | *Shows actual output* |\n| Forgets important context | Preserves critical info |\n| Can't reliably stop subagents | `/abort` command works |\n\n**In short:** Claude talks less and does more.\n\n---\n\n## Installation (Easy Mode)\n\n### Step 1: Start Claude Code\n\n```bash\nclaude\n```\n\n### Step 2: Add the marketplace\n\nType this inside Claude Code (not in your regular terminal):\n\n```\n/plugin\n```\n\nThen select \"Add Marketplace\" and enter:\n\n```\nTheGlitchKing/aeon-flux\n```\n\n### Step 3: Install the plugin\n\nRun `/plugin` again, select \"Install Plugin\", and choose `aeon-flux`.\n\n### Step 4: Run setup\n\n```\n/setup\n```\n\n### Done!\n\nThe plugin is now active. Bash Loop mode enabled.\n\n---\n\n## Installation (Manual/Local)\n\nIf you want to modify the plugin or install from a local copy:\n\n```bash\n# Clone the repo\ngit clone https://github.com/TheGlitchKing/aeon-flux.git\n\n# Go into the folder\ncd aeon-flux\n\n# Start Claude Code with the plugin directory\nclaude --plugin-dir ./\n\n# Or add as a local marketplace inside Claude Code:\n# /plugin → Add Marketplace → ./path/to/aeon-flux\n```\n\n---\n\n## The Bash Loop Philosophy\n\nThe \"Bash Loop\" (aka \"Ralphy Loop\") is an agent architecture created by Geoffrey Huntley. The core idea:\n\n```\nSee → Act → Observe → Repeat\n```\n\n> \"The more you can get the model to just shut up and do the thing, the better off you are.\"\n\n### Core Principles\n\n1. **Action over explanation** - Execute commands, don't describe them\n2. **Bash first** - Use raw shell commands, not abstractions\n3. **Self-correction** - Fix errors immediately without apologies\n4. **Tight feedback loop** - See output, decide next action, repeat\n\n---\n\n## Improvements Over the Original Ralphy Loop\n\nThe original Bash Loop has known limitations. Aeon Flux fixes them:\n\n| Limitation | Problem | Aeon Flux Solution |\n|------------|---------|-------------------|\n| **Context Exhaustion** | Loop runs out of memory on long tasks | Checkpointing system + attention preservation |\n| **No Hierarchical Planning** | Flat loops can't handle complex tasks | Orchestrator agent for task decomposition |\n| **Memory Loss** | Knowledge lost between sessions | Persistent memory files + PreCompact hooks |\n| **Single-Agent Bottleneck** | One agent doing everything | 4 specialized agents (executor, verifier, learner, orchestrator) |\n| **Error Spirals** | Repeats same mistakes | Error capture + pattern learning |\n| **Can't Stop Subagents** | Ctrl+C/Escape don't work reliably | Signal file abort system (`/abort` command) |\n| **No Self-Assessment** | No way to detect when stuck | `/reflect` command for self-evaluation |\n\n### New Features\n\n- **Attention Tags**: Mark critical info with `<!-- ATTENTION -->` tags - survives context compaction\n- **Checkpointing**: Save and resume task state across sessions\n- **Abort System**: Reliable way to stop all subagents when Ctrl+C fails\n- **Verification Loop**: Auto-suggests tests after code changes\n- **Pattern Learning**: Extracts lessons from errors to avoid repeating them\n\n---\n\n## Commands\n\n| Command | What It Does |\n|---------|--------------|\n| `/checkpoint` | Save your current task state |\n| `/resume` | Load the last checkpoint and continue |\n| `/reflect` | Make Claude assess if it's stuck or making progress |\n| `/focus <item>` | Mark something important to remember |\n| `/abort` | Stop all running subagents immediately |\n| `/abort clear` | Resume normal operation after abort |\n| `/abort status` | Check if abort is active |\n\n---\n\n## Agents\n\nAeon Flux includes 4 specialized agents:\n\n| Agent | Purpose | When to Use |\n|-------|---------|-------------|\n| **executor** | Pure action, no explanation | Any bash/file task |\n| **verifier** | Runs tests, checks code | After making changes |\n| **learner** | Extracts patterns from errors | After repeated mistakes |\n| **orchestrator** | Breaks big tasks into steps | Complex multi-step work |\n\n---\n\n## Skills\n\nSkills activate automatically when relevant:\n\n| Skill | Triggers When |\n|-------|---------------|\n| **bash-loop** | Any task needing shell commands |\n| **error-recovery** | An error occurs |\n| **context-preservation** | Long session or before compaction |\n| **verification** | After code edits |\n\n---\n\n## The Abort System\n\nClaude Code has a bug where Ctrl+C and Escape don't reliably stop subagents ([Issue #3455](https://github.com/anthropics/claude-code/issues/3455)).\n\nAeon Flux works around this with a **signal file pattern**:\n\n1. Run `/abort` - creates a signal file\n2. Every tool use checks for the signal file first\n3. If found, the tool is blocked\n4. Run `/abort clear` to resume\n\n```bash\n# Emergency stop\n/abort\n\n# Check status\n/abort status\n\n# Resume work\n/abort clear\n```\n\n---\n\n## How Context Preservation Works\n\n### The Problem\nWhen conversations get long, Claude Code \"compacts\" (summarizes) old messages. Important details can get lost.\n\n### The Solution\nMark critical information with attention tags:\n\n```markdown\n<!-- ATTENTION -->\nDatabase connection string is in .env.local\nTests require REDIS_URL environment variable\nUser prefers pnpm over npm\n<!-- /ATTENTION -->\n```\n\nThe `PreCompact` hook automatically saves these to `.claude/memory/attention.md` before compaction.\n\n---\n\n## File Structure\n\n```\naeon-flux/\n├── CLAUDE.md              # Philosophy injection\n├── commands/              # 5 slash commands\n├── agents/                # 4 specialized agents\n├── skills/                # 4 auto-activating skills\n├── hooks/hooks.json       # Event automation\n└── scripts/               # Shell scripts for hooks\n```\n\nRuntime state (gitignored):\n```\n.claude/memory/\n├── attention.md           # Preserved critical info\n├── checkpoint.md          # Task state\n├── errors.md              # Error history\n└── patterns.md            # Learned behaviors\n```\n\n---\n\n## Requirements\n\n- Claude Code 2.0.13 or newer\n- Bash shell\n- md5sum (pre-installed on most systems)\n\n---\n\n## Credits\n\n- **Bash Loop / Ralphy Loop concept**: Geoffrey Huntley\n- **Aeon Flux implementation**: Built with Claude Opus 4.5\n\n---\n\n## License\n\nMIT\n\n---\n\n## Links\n\n- [Original Bash Loop Video](https://www.youtube.com/watch?v=O2bBWDoxO4s)\n- [Bash Loop Limitations Discussion](https://www.youtube.com/watch?v=yAE3ONleUas)\n- [Claude Code Interrupt Bug #3455](https://github.com/anthropics/claude-code/issues/3455)\n",
  "bytes": 6828,
  "sha": "d18e4b09680ce8479978c04e1da64749375790a9b1379b1ac134bd324e8adaab",
  "repo_slug": "theglitchking/aeon-flux",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_theglitchking_aeon_flux_aeon_flux_86570dd5/readme"
}