Claude Mycelium 🍄

Autonomous AI agents that improve your codebase - Multi-agent swarm intelligence for continuous code evolution.

Claude Mycelium coordinates autonomous AI agents to improve code quality through gradient-based optimization. Like a mycelium network, agents communicate through signals, learn from failures, and self-organize to reduce complexity, fix bugs, and pay down technical debt.

🚀 Quick Start

Installation

npm install -g claude-mycelium

Setup

# Initialize in your project
npx claude-mycelium init

# Set your Anthropic API key
export ANTHROPIC_API_KEY=sk-ant-...

CLI Commands

# Interactive mode - chat with mycelium to spawn agents
npx claude-mycelium grow

# Check code quality scores
npx claude-mycelium gradients ./src

# View system status
npx claude-mycelium status

# Check API costs
npx claude-mycelium cost

# Run garbage collection
npx claude-mycelium gc

# Single task mode
npx claude-mycelium grow --task "fix bugs in src/api.ts"

✨ Features

• 5 Quality Signals - Complexity, churn, technical debt, error rate, centrality
• 4 Agent Modes - Error Reducer, Complexity Reducer, Debt Payer, Stabilizer
• Swarm Coordination - Multi-agent parallel execution with file locking
• Learning System - Inhibitors and quarantine prevent repeated failures
• Automatic Rollback - Reverts changes if tests fail
• Cost Tracking - Monitor LLM API usage and efficiency

🎯 How It Works

Claude Mycelium treats code improvement as gradient descent:

1. Measure - Calculate quality gradients (complexity, debt, errors)
2. Prioritize - Find files with highest improvement potential
3. Execute - Spawn agents to make improvements in parallel
4. Validate - Run tests and check for regressions
5. Learn - Record outcomes to improve future decisions

Agents coordinate through inhibitor signals - files with repeated failures get quarantined, preventing wasted resources.

🛠️ Configuration

Environment Variables

ANTHROPIC_API_KEY=sk-ant-...    # Required
LOG_LEVEL=info                  # Optional: debug, info, warn, error

Project Config

Create .agent-meta/config.json:

{
  "weights": {
    "complexity": 0.3,
    "churn": 0.2,
    "debt": 0.3,
    "error": 0.1,
    "centrality": 0.1
  }
}

📊 Current Status

• Phase 1 ✅ - Signal system and gradient calculation
• Phase 2 ✅ - LLM integration and agent execution
• Phase 3 ✅ - Concurrency and file locking
• Phase 4 ✅ - Inhibitors and quarantine system
• Phase 5 ✅ - Task planning and execution
• Phase 7 ✅ - CLI and garbage collection
• Phase 6 🚧 - Watch mode (coming soon)
• Phase 8 📋 - Multi-file orchestration
• Phase 9 📋 - Distributed coordination

90% Complete - Meta-circular development ready (system can improve itself)

🔒 Safety Features

• Atomic File Locks - Prevents concurrent modifications
• Backup System - Automatic backups before changes
• Test Validation - Automatic rollback on test failures
• Quarantine - Isolates problematic files after repeated failures
• Path Safety - Protects .git/ and node_modules/

📦 Programmatic API

For advanced use cases, you can use the TypeScript API:

import { executeAgent, calculateGradient } from 'claude-mycelium';

// Calculate quality gradient
const gradient = await calculateGradient('src/app.ts');
console.log(`Score: ${gradient.score}`);

// Execute agent
const result = await executeAgent('src/app.ts', 'complexity_reducer', {
  dryRun: false
});

See API Documentation for details.

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

📄 License

MIT License - see LICENSE for details.

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Made with Claude Opus 4.5 🍄✨

Continuous code evolution through autonomous AI agents