DEV Community

S.P.C. Technology LTD.
S.P.C. Technology LTD.

Posted on

Minions: Building Self-Learning AI Agent Swarms That Actually Ship Code

#javascript #ai #opensource #automation

Why i Built This !!

I've been building AI-assisted development tools, and I kept running into the same problems:

  1. One-shot AI - Ask a question, get an answer, context lost
  2. No memory - Same mistakes repeated endlessly
  3. No collaboration - AI tools don't talk to each other
  4. No autonomy - Still requires constant human oversight
  5. Most Annoying - TOKENS

Minions addresses all of these:

  • Persistent memory via SQLite-backed MemoryStore
  • Learning from experience via Reinforcement Learning
  • Agent collaboration via EventBus and KnowledgeBrain
  • Autonomous operation via event-driven architecture
  • Less Tokens via built-in agents

TL;DR

Minions is an open-source framework for building AI agent swarms that:

  • Learn from experience (Q-learning)
  • Share knowledge (KnowledgeBrain)
  • Generate new skills (DynamicSkillGenerator)
  • Teach each other (CrossAgentTeacher)
  • Fix tests autonomously (AutonomousLoopManager)
  • Roll back on failure (RollbackManager)

26 specialized agents. 80+ event types. One goal: AI that actually helps you ship code.

What if your development team included AI agents that could learn from their mistakes, teach each other new skills, and autonomously fix failing tests at 3 AM?

That's exactly what we built with Minions - an open-source, event-driven framework for orchestrating autonomous AI agents. And yes, they're named after the yellow creatures from the movies.

Minions | AI That Dreams

The Problem We Solved

Most AI coding assistants are reactive - you ask, they answer. But real development workflows are complex:

  • Tests fail at random times
  • Multiple systems need to stay in sync
  • Security vulnerabilities need constant monitoring
  • Documentation drifts from code
  • New team members need onboarding

We wanted AI that works with us, not just for us. AI that:

  1. Monitors - Watches for events and reacts autonomously
  2. Learns - Gets better at fixing problems over time
  3. Collaborates - Agents teaching agents, sharing knowledge
  4. Self-heals - Automatically fixes issues without human intervention

Meet the Minions

Our framework includes 26 specialized agents, each named after characters from the Despicable Me universe:

The Core Team

Agent Character Superpower
Gru The mastermind Web interface & conversational AI
Dr. Nefario The inventor Converts requirements to execution plans
Silas Resource allocator Project connections & framework detection
Lucy Self-improvement engine Autonomous completion loops
Tom Vigilant security STRIDE threat modeling & vulnerability scanning

The Specialists

Agent Character Superpower
Bob The tester Multi-platform testing & mutation analysis
Kevin Performance guru Profiling & bottleneck detection
Dave Database wizard Schema design & query optimization
Stuart Backend builder Routes, models, services, middleware
Agnes Frontend crafter Components, hooks, stores, forms
Otto Flutter specialist Widgets, blocs, pages, localization

Architecture: Event-Driven Everything

The secret sauce is our event-driven architecture. Instead of rigid pipelines, agents communicate through 80+ event types:

┌────────────────────────────────────────────────────────────────────────┐
│                         CLIENT INTERFACE                                │
│    Gru (Web UI)  →  Dr. Nefario (Planner)  →  Tom (Security)           │
├────────────────────────────────────────────────────────────────────────┤
│                         ORCHESTRATION                                   │
│    Orchestrator  →  DependencyGraph  →  AutonomousLoopManager          │
├────────────────────────────────────────────────────────────────────────┤
│                      SPECIALIZED AGENTS                                 │
│    Tester  │  Docker  │  GitHub  │  Database  │  Performance           │
├────────────────────────────────────────────────────────────────────────┤
│                      LEARNING & EVOLUTION                               │
│    KnowledgeBrain  │  ReinforcementLearner  │  DynamicSkillGenerator   │
├────────────────────────────────────────────────────────────────────────┤
│                     FOUNDATION SERVICES                                 │
│    EventBus  │  MemoryStore  │  StateMachine  │  CircuitBreaker        │
└────────────────────────────────────────────────────────────────────────┘
Enter fullscreen mode Exit fullscreen mode

Here's how simple it is to wire agents together:

import { initializeMinions, createAgent, EventTypes } from 'minions';

const { orchestrator, eventBus } = await initializeMinions();

// Create agents
const fetchAgent = createAgent({
  name: 'fetch-agent',
  execute: async () => {
    const data = await fetchFromAPI();
    eventBus.publish(EventTypes.CODE_GENERATED, { files: data });
  }
});

const processAgent = createAgent({
  name: 'process-agent',
  execute: async () => {
    // This runs AFTER fetch-agent completes
    await processData();
  }
});

// Register with dependencies
orchestrator.registerAgent('fetch-agent', async () => fetchAgent, []);
orchestrator.registerAgent('process-agent', async () => processAgent, ['fetch-agent']);

// Execute in dependency order
await orchestrator.execute();
Enter fullscreen mode Exit fullscreen mode

The Magic: Self-Learning Agents

Here's where it gets interesting. Minions don't just execute - they learn.

Reinforcement Learning

Every time an agent succeeds or fails, it learns:

import { getReinforcementLearner } from 'minions';

const learner = getReinforcementLearner();

// Agent fixes a null reference error
await learner.recordExperience({
  state: 'test_failure_null_reference',
  action: 'apply_optional_chaining',
  reward: 1.0,  // SUCCESS!
  nextState: 'tests_passing'
});

// Next time it sees a similar error:
const bestAction = learner.selectAction('test_failure_null_reference');
// Returns: 'apply_optional_chaining' (learned from experience)
Enter fullscreen mode Exit fullscreen mode

The learner uses Q-learning with Thompson sampling:

Q(s,a) ← Q(s,a) + α[r + γ·max_a'Q(s',a') - Q(s,a)]
Enter fullscreen mode Exit fullscreen mode

Translation: It balances exploration (trying new things) with exploitation (using what works).

Knowledge Brain: Collective Intelligence

Agents share knowledge through a distributed brain:

import { getKnowledgeBrain } from 'minions';

const brain = getKnowledgeBrain();

// Stuart (backend agent) learns a pattern
await brain.store({
  type: 'CODE_PATTERN',
  topic: 'null-check-fix',
  content: {
    pattern: 'optional-chaining',
    code: 'obj?.nested?.value',
    effectiveness: 0.94
  },
  confidence: 0.95
});

// Agnes (frontend agent) queries for similar patterns
const patterns = await brain.query({
  type: 'CODE_PATTERN',
  similarity: 'null reference error fix'
});
// Gets Stuart's pattern - knowledge shared!
Enter fullscreen mode Exit fullscreen mode

Dynamic Skill Generation

The wildest part? Agents can generate new skills from patterns they observe:

import { getDynamicSkillGenerator } from 'minions';

const skillGen = getDynamicSkillGenerator();

// System detects recurring pattern
const skill = await skillGen.generateSkill({
  pattern: {
    name: 'async-error-wrapper',
    description: 'Wrap async functions with try-catch and logging',
    examples: [/* observed patterns */]
  }
});

// Canary deploy to 10% of requests
await skillGen.deployCanary(skill.id, { percentage: 10 });

// If metrics look good, promote to production
await skillGen.approveSkill(skill.id);
Enter fullscreen mode Exit fullscreen mode

The skill generation pipeline:

Pattern Detected → LLM Generates Skill → Sandboxed Testing → Canary Deploy → A/B Test → Production
Enter fullscreen mode Exit fullscreen mode

Autonomous Fix Loops

When tests fail, Minions spring into action:

import { getAutonomousLoopManager } from 'minions';

const loopManager = getAutonomousLoopManager();

// Register which agents handle which failures
loopManager.registerAgentMatcher((failure) => {
  if (failure.file?.includes('/api/')) return 'backend-agent';
  if (failure.file?.includes('/components/')) return 'frontend-agent';
  if (failure.file?.includes('.test.')) return 'tester-agent';
  return null;
});

// Loop activates automatically on TESTS_FAILED events
// 1. Analyzes failure
// 2. Creates checkpoint
// 3. Applies fix (Tier 1: patterns, Tier 2: agent-specific)
// 4. Re-runs tests
// 5. Commits or rollbacks
Enter fullscreen mode Exit fullscreen mode

The system creates Git checkpoints before every fix attempt, so failures can be safely rolled back.

Getting Started in 60 Seconds

Docker (Recommended) 

git clone https://github.com/Inweb-eg/minions.git
cd minions/docker
docker compose up -d
docker exec minions-ollama ollama pull deepseek-coder:6.7b
docker restart minions

# Open http://localhost:2505
Enter fullscreen mode Exit fullscreen mode

Node.js 

git clone https://github.com/Inweb-eg/minions.git
cd minions
npm run install:all
node index.js --gru
Enter fullscreen mode Exit fullscreen mode

You'll see Gru's web interface - a conversational AI that helps you plan and execute projects:

Gru Interface

Real-World Example: Building a REST API

Let's say you want to build a user authentication API. Here's how Minions handles it:

1. Talk to Gru

You: "I need a REST API for user authentication with JWT tokens"
Gru: "I'll help you build that. Let me scan your project first..."
Enter fullscreen mode Exit fullscreen mode

2. Dr. Nefario Creates the Plan

{
  "tasks": [
    { "type": "backend", "action": "generate-model", "name": "User" },
    { "type": "backend", "action": "generate-route", "name": "auth" },
    { "type": "backend", "action": "generate-middleware", "name": "jwt" },
    { "type": "testing", "action": "generate-tests", "target": "auth" }
  ],
  "dependencies": {
    "auth-route": ["user-model", "jwt-middleware"]
  }
}
Enter fullscreen mode Exit fullscreen mode

3. Tom Validates Security

✓ JWT secret not hardcoded
✓ Password hashing detected (bcrypt)
✓ Rate limiting recommended → Added to plan
✓ No SQL injection vulnerabilities
Enter fullscreen mode Exit fullscreen mode

4. Agents Execute in Order

  • Stuart generates User model, auth routes, JWT middleware
  • Bob generates and runs tests
  • If tests fail → AutoFixer attempts repair
  • If still failing → Stuart gets specific feedback

5. Lucy Ensures Completion

  • Detects gaps: "Missing password reset endpoint"
  • Generates additional tasks
  • Loops until 100% complete or max iterations

The Event System

Everything communicates through events. Here are some key ones:

// Agent Lifecycle
AgentEvents.AGENT_STARTED
AgentEvents.AGENT_COMPLETED
AgentEvents.AGENT_FAILED

// Testing
TestEvents.TESTS_STARTED
TestEvents.TESTS_COMPLETED
TestEvents.TESTS_FAILED  // Triggers autonomous fix loop

// Security (Tom)
SecurityEvents.VULNERABILITY_FOUND
SecurityEvents.RISK_IDENTIFIED
SecurityEvents.THREAT_MITIGATED

// Learning
LearningEvents.PATTERN_DETECTED
LearningEvents.SKILL_GENERATED
LearningEvents.POLICY_UPDATED
Enter fullscreen mode Exit fullscreen mode

Subscribe to any event:

eventBus.subscribe(EventTypes.TESTS_FAILED, 'my-handler', (data) => {
  console.log(`Tests failed in ${data.file}`);
  console.log(`Failures: ${data.failures.length}`);
});
Enter fullscreen mode Exit fullscreen mode

Built-in Skills

Agents come with pre-built skills you can use directly:

// Auto-fix test failures
const fixer = getAutoFixer({ projectRoot: '/path/to/project' });
await fixer.handleTestFailure({ testOutput, failedTests });

// Code review
const reviewer = getCodeReviewer();
const review = await reviewer.review('src/api.js');
// { qualityScore: 85, issues: [...], suggestions: [...] }

// Security scanning
const scanner = getSecurityScanner();
const results = await scanner.scan('/path/to/project');
// Detects: SQL injection, XSS, hardcoded secrets, weak auth

// Dependency analysis
const analyzer = getDependencyAnalyzer();
const deps = await analyzer.analyze('/path/to/project');
// { outdated: [...], vulnerabilities: [...], unused: [...] }
Enter fullscreen mode Exit fullscreen mode

The Learning Dashboard

Access the Learning Control Center at http://localhost:2505/evolve:

  • RL Policy Viewer - See Q-values for state-action pairs
  • Skill Manager - Approve/reject generated skills
  • A/B Test Monitor - Track skill experiments
  • Teaching Sessions - Watch agents teach each other
  • Pattern Detection - See recurring behaviors 
GET  /api/learning/stats          # Learning statistics
GET  /api/learning/skills         # Generated skills
GET  /api/learning/policy         # RL Q-table
POST /api/learning/skills/:id/approve  # Approve skill for production
POST /api/learning/teaching/start      # Start teaching session
Enter fullscreen mode Exit fullscreen mode

Cross-Agent Teaching

This is my favorite feature. Agents can teach each other:

import { getCrossAgentTeacher } from 'minions';

const teacher = getCrossAgentTeacher();

// Stuart (backend expert) creates curriculum
const curriculum = await teacher.createCurriculum({
  skill: 'input-validation',
  levels: [
    { name: 'Basic', topics: ['null-checks', 'type-guards'] },
    { name: 'Advanced', topics: ['schema-validation', 'sanitization'] }
  ]
});

// Agnes (frontend agent) learns from Stuart
const session = await teacher.startTeachingSession({
  fromAgent: 'stuart-backend',
  toAgent: 'agnes-frontend',
  skill: 'input-validation'
});

// Track mastery
const competencies = await teacher.getAgentCompetencies('agnes-frontend');
// { 'input-validation': { level: 'Advanced', score: 0.92 } }
Enter fullscreen mode Exit fullscreen mode

Performance & Scalability

Some numbers from our testing:

Metric Value
Event throughput ~1000/min
Agent execution 50ms - 5min
Memory (typical) 15-35 MB
Max concurrent agents 10-20
Event history 1000 events

The framework is designed for development workflows, not production inference. It's optimized for correctness and learning, not raw speed.

What's Next

We're actively working on:

  • Multi-project orchestration - Minions managing microservices
  • Custom LLM adapters - Beyond Ollama/Gemini
  • Visual workflow builder - Drag-and-drop agent configuration
  • Plugin marketplace - Community-contributed agents
  • Cloud deployment - Managed Minions service

Get Involved

Minions is open source and we'd love your contributions:

Star the repo if you find it interesting!

Try It Now 

# Clone
git clone https://github.com/Inweb-eg/minions.git
cd minions

# Install
npm run install:all

# Run tests
npm test

# Start Gru
node index.js --gru

# Visit http://localhost:2505
Enter fullscreen mode Exit fullscreen mode

Or with Docker:

cd docker
docker compose up -d
docker exec minions-ollama ollama pull deepseek-coder:6.7b
docker restart minions
Enter fullscreen mode Exit fullscreen mode

Built with love by Kareem Hussein at Inweb Software Solutions

What would you build with self-learning AI agents? Let me know in the comments!

Top comments (0)