aeon-flux

Aeon Flux

A Claude Code plugin that makes Claude faster, smarter, and more reliable by implementing the Bash Loop architecture.

Inspired by Geoffrey Huntley's "Ralphy Loop" - enhanced with solutions for its known limitations.

---

What Does This Do?

Aeon Flux changes how Claude Code behaves:

Before (Default Claude)	After (Aeon Flux)
"Let me explain what I'm going to do..."	Just does it
"I apologize for the error..."	Fixes it silently
"Here's a summary of the output..."	Shows actual output
Forgets important context	Preserves critical info
Can't reliably stop subagents	/abort command works

In short: Claude talks less and does more.

---

Installation (Easy Mode)

Step 1: Start Claude Code

claude

Step 2: Add the marketplace

Type this inside Claude Code (not in your regular terminal):

/plugin

Then select "Add Marketplace" and enter:

TheGlitchKing/aeon-flux

Step 3: Install the plugin

Run /plugin again, select "Install Plugin", and choose aeon-flux.

Step 4: Run setup

/setup

Done!

The plugin is now active. Bash Loop mode enabled.

---

Installation (Manual/Local)

If you want to modify the plugin or install from a local copy:

# Clone the repo
git clone https://github.com/TheGlitchKing/aeon-flux.git

# Go into the folder
cd aeon-flux

# Start Claude Code with the plugin directory
claude --plugin-dir ./

# Or add as a local marketplace inside Claude Code:
# /plugin → Add Marketplace → ./path/to/aeon-flux

---

The Bash Loop Philosophy

The "Bash Loop" (aka "Ralphy Loop") is an agent architecture created by Geoffrey Huntley. The core idea:

See → Act → Observe → Repeat

"The more you can get the model to just shut up and do the thing, the better off you are."

Core Principles

1. Action over explanation - Execute commands, don't describe them
2. Bash first - Use raw shell commands, not abstractions
3. Self-correction - Fix errors immediately without apologies
4. Tight feedback loop - See output, decide next action, repeat

---

Improvements Over the Original Ralphy Loop

The original Bash Loop has known limitations. Aeon Flux fixes them:

Limitation	Problem	Aeon Flux Solution
Context Exhaustion	Loop runs out of memory on long tasks	Checkpointing system + attention preservation
No Hierarchical Planning	Flat loops can't handle complex tasks	Orchestrator agent for task decomposition
Memory Loss	Knowledge lost between sessions	Persistent memory files + PreCompact hooks
Single-Agent Bottleneck	One agent doing everything	4 specialized agents (executor, verifier, learner, orchestrator)
Error Spirals	Repeats same mistakes	Error capture + pattern learning
Can't Stop Subagents	Ctrl+C/Escape don't work reliably	Signal file abort system (/abort command)
No Self-Assessment	No way to detect when stuck	/reflect command for self-evaluation

New Features

• Attention Tags: Mark critical info with <!-- ATTENTION --> tags - survives context compaction
• Checkpointing: Save and resume task state across sessions
• Abort System: Reliable way to stop all subagents when Ctrl+C fails
• Verification Loop: Auto-suggests tests after code changes
• Pattern Learning: Extracts lessons from errors to avoid repeating them

---

Commands

Command	What It Does
/checkpoint	Save your current task state
/resume	Load the last checkpoint and continue
/reflect	Make Claude assess if it's stuck or making progress
/focus <item>	Mark something important to remember
/abort	Stop all running subagents immediately
/abort clear	Resume normal operation after abort
/abort status	Check if abort is active

---

Agents

Aeon Flux includes 4 specialized agents:

Agent	Purpose	When to Use
executor	Pure action, no explanation	Any bash/file task
verifier	Runs tests, checks code	After making changes
learner	Extracts patterns from errors	After repeated mistakes
orchestrator	Breaks big tasks into steps	Complex multi-step work

---

Skills

Skills activate automatically when relevant:

Skill	Triggers When
bash-loop	Any task needing shell commands
error-recovery	An error occurs
context-preservation	Long session or before compaction
verification	After code edits

---

The Abort System

Claude Code has a bug where Ctrl+C and Escape don't reliably stop subagents (Issue #3455).

Aeon Flux works around this with a signal file pattern: