GitHub - camplight/claude-mycelium: Autonomous AI agents that improve your codebase - Multi-agent swarm intelligence for continuous code evolution.

3 min read Original article ↗

npm version License: MIT Tests TypeScript

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

Made with Claude Opus 4.5 🍄✨

Continuous code evolution through autonomous AI agents