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.

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        │
└────────────────────────────────────────────────────────────────────────┘

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();

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)

The learner uses Q-learning with Thompson sampling:

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

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!

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);

The skill generation pipeline:

Pattern Detected → LLM Generates Skill → Sandboxed Testing → Canary Deploy → A/B Test → Production

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

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

Node.js

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

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

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..."

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"]
}
}

3. Tom Validates Security

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

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

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}`);
});

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: [...] }

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

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 } }

Why We Built This

I’ve been building AI-assisted development tools for years, 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

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

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:

• GitHub: github.com/Inweb-eg/minions
• Documentation: Comprehensive docs in /docs
• Discord: Join our community (link in repo)

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

Or with Docker:

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

---

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.

---

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!