AttractorFlow
A Claude Code plugin that monitors and steers multi-agent trajectories using
dynamical systems theory. Agent states are embedded in semantic space;
finite-time Lyapunov exponents (FTLE) classify the trajectory regime and
prescribe interventions before a task gets stuck, oscillates, or diverges.
How it works
Every agent step is embedded into a 384-dimensional vector using
all-MiniLM-L6-v2. The MCP server tracks a FIFO buffer of embeddings and
computes:
- FTLE —
λ = (1/W) × Σ ln(d_{i+1} / d_i) over a sliding window
- Autocorrelation at lags 1–10 for cycle detection
- Basin depth from distance variance (stability estimate)
- Bifurcation proximity via k-means cluster separation
These signals drive regime classification and route the orchestrator to the
right intervention.
Regimes
| Regime | λ signal | Action |
|---|
| CONVERGING | < −0.05 | Continue, add convergence pressure |
| CYCLING | ≈ 0, autocorr peak | Continue if amplitude ↓, perturb if stable |
| EXPLORING | 0.05–0.25 | OK in design phase, pressure in impl phase |
| DIVERGING | trend > 0, mean_d > 1 | Restore checkpoint immediately |
| STUCK | v ≈ 0, no trend | Inject perturbation, spawn explorer |
| OSCILLATING | ≈ 0, lag-1 autocorr < −0.4 | Break symmetry with asymmetric constraint |
| PLATEAU | v ≈ 0, trend < −0.01 | Nudge (small specific constraint) |
Setup
Install uv (one-time, ~5 MB binary):
curl -LsSf https://astral.sh/uv/install.sh | sh
Restart Claude Code. The MCP server registers automatically via plugin auto-discovery.
Python dependencies (sentence-transformers, scikit-learn, etc.) load on the first
attractorflow_record_state call — no venv, pip, or claude mcp add needed.
Session scoping (optional)
For multi-project or benchmark use, set env vars in your shell or in a
project .mcp.json env block:
| Env var | Default | Effect |
|---|
ATTRACTORFLOW_SESSION_ID | (none) | Named session → ~/.attractorflow/sessions/<id>.json |
ATTRACTORFLOW_DISABLE_PERSISTENCE | 0 | 1 = no disk I/O (benchmark / CI mode) |
ATTRACTORFLOW_BUFFER_CAPACITY | 100 | Override buffer size |
ATTRACTORFLOW_WINDOW | 8 | Override FTLE window |
MCP tools
All tools are direct Claude tool calls — not bash commands.
| Tool | When to call |
|---|
attractorflow_record_state | After every agent step |
attractorflow_get_regime | Every 3–5 steps |
attractorflow_get_lyapunov | For detailed stability analysis |
attractorflow_get_trajectory | For visualization |
attractorflow_get_basin_depth | Before committing to an approach |
attractorflow_detect_bifurcation | Every 10 steps or on complex tasks |
attractorflow_inject_perturbation | When STUCK or OSCILLATING |
attractorflow_checkpoint | After tests pass or clean deliverable |
Agents
Three specialist agents are defined in .claude/agents/:
- attractor-orchestrator — meta-orchestrator; reads regime every 3–5 steps
and routes to the right subagent
- explorer-agent — covers solution space when STUCK or PITCHFORK detected
- convergence-agent — drives chosen approach to completion; halts if λ rises
Commands
/attractor-status — current regime, λ, recommended action/phase-portrait — ASCII trajectory visualization
Project structure
attractorflow/
mcp-server/ # FastMCP server (8 tools)
server.py # tool definitions and lifespan
phase_space.py # embedding buffer, PCA, distance series
lyapunov.py # FTLE computation, autocorrelation
classifier.py # regime classification, action prescription
bifurcation.py # k-means bifurcation detection
requirements.txt
claude-plugin/ # Claude Code plugin integration
skill/ # SKILL.md and reference materials
.claude/
CLAUDE.md # project context loaded into every session
agents/ # attractor-orchestrator, explorer, convergence
commands/ # /attractor-status, /phase-portrait
.mcp.json # MCP server registration
docs/
PRD.md
ADR-001.md
research.md # theoretical foundations
simulation/ # synthetic trajectory scenarios
demo/ # proof-of-work demo runner and dashboard
References
- Drela, M. (1989). XFOIL: An analysis and design system for low Reynolds
number airfoils. Lecture Notes in Engineering, 54.
- Wang, X. et al. (2025). Stable attractors in multi-agent LLM trajectories.
- Lyapunov, A. M. (1892). The general problem of the stability of motion.
License
MIT — see LICENSE.
