11 agents · 41 MCP tools · 6 LLM providers · SQLite + FTS5 · Web dashboard · Agent Identity · Drift Detection · Resource Exhaustion Monitoring

What It Does

aistack helps you coordinate multiple specialized AI agents to work together on complex tasks. Think of it as a team of AI specialists:

Instead of asking one AI to do everything, you can:

• Spawn a Coder agent to write code
• Spawn an Adversarial agent to review and break it
• Spawn a Tester agent to write tests
• Spawn a Documentation agent to document it
• Store learnings in persistent memory for future use

How it works:

1. Spawn specialized agents - Each agent has specific expertise (coding, testing, reviewing, etc.)
2. They communicate through a message bus - Agents can coordinate and share information
3. Memory persists across sessions - Agents remember patterns, decisions, and learnings
4. Adversarial validation - Code is automatically reviewed and improved through iterative feedback
5. Integrate with Claude Code - Use agents directly from your IDE via MCP protocol

Perfect for:

• Code generation with automatic review cycles
• Multi-step development workflows (design → code → test → document)
• Building institutional knowledge that persists across projects
• Automating complex tasks that need different types of expertise

Example Workflow

You ask: "Create a login API endpoint with tests"

aistack:
1. Spawns a Coder agent → writes the API code
2. Spawns an Adversarial agent → tries to break it, finds security issues
3. Coder fixes the issues
4. Spawns a Tester agent → writes comprehensive tests
5. Spawns a Documentation agent → generates API docs
6. Stores patterns in memory → "Always use bcrypt for passwords"

Next time: The memory helps agents make better decisions automatically

Tech Stack

Node.js 20+	TypeScript	SQLite + FTS5	Vitest
React 18	Material-UI	Vite	Anthropic
OpenAI	Ollama	GitHub Actions	NPM Package

✨ Features

🤖 11 Specialized Agent Types

Each agent has specific expertise and capabilities:

• Coder - Write, edit, and refactor code
• Researcher - Search and analyze codebases, gather information
• Tester - Write and run tests, coverage analysis
• Reviewer - Code review and best practices
• Adversarial - Attack code to find vulnerabilities (used in review loops)
• Architect - System design and technical decisions
• Coordinator - Orchestrate multiple agents for complex tasks
• Analyst - Data analysis and performance profiling
• DevOps - Deployment, infrastructure, monitoring
• Documentation - Generate and maintain documentation
• Security Auditor - Security audits, compliance, threat modeling

💾 Persistent Memory System

Knowledge that survives across sessions:

• SQLite with FTS5 - Fast full-text search across all memory
• Vector Embeddings - Optional semantic search (OpenAI/Ollama)
• Namespaces & Tags - Organize memory by project, topic, or team
• Version History - Track changes and rollback if needed
• Memory Relationships - Link related concepts together

🔄 Adversarial Review Loop

Automatic code improvement through iterative feedback:

1. Coder agent generates code
2. Adversarial agent reviews and tries to break it
3. Coder fixes issues
4. Repeat up to 3 times until approved

Result: More robust, secure code with fewer bugs.

🪪 Agent Identity v1

Persistent agent identities with lifecycle management:

• Stable UUIDs - Agents have persistent agent_id across executions
• Lifecycle States - created → active → dormant → retired
• Capabilities Tracking - Store and version agent capabilities
• Full Audit Trail - Every identity change is logged
• Agent-Scoped Memory - Memory namespaces owned by specific agents

🎯 Semantic Drift Detection

Detect when task descriptions are semantically similar to ancestors:

• Embedding-based Similarity - Uses OpenAI or Ollama embeddings
• Configurable Thresholds - threshold (block/warn) and warningThreshold (warn only)
• Two Behaviors - warn (log and allow) or prevent (block creation)
• Task Relationships - Track parent_of, derived_from, depends_on, supersedes
• Metrics & Events - Full logging for drift detection analysis

🛡️ Resource Exhaustion Monitoring

Detect and prevent runaway agents consuming excessive resources:

• Per-Agent Tracking - Track files accessed, API calls, subtasks spawned, tokens consumed
• Phase Progression - normal → warning → intervention → termination
• Configurable Thresholds - Set limits for each resource type
• Pause/Resume Control - Automatically pause agents exceeding thresholds
• Deliverable Checkpoints - Reset time-based tracking when agents produce results
• Slack Notifications - Alert on warnings, interventions, and terminations

🎯 41 MCP Tools for Claude Code

Control aistack directly from Claude Code IDE:

• 6 agent tools (spawn, list, stop, status, types, update)
• 8 identity tools (create, get, list, update, activate, deactivate, retire, audit)
• 5 memory tools (store, search, get, list, delete) — with agent-scoped memory support
• 8 task tools (create, assign, complete, list, get, check_drift, get_relationships, drift_metrics)
• 4 session tools (start, end, status, active)
• 3 system tools (status, health, config)
• 7 GitHub tools (issues, PRs, repo info)

🌐 Web Dashboard

Real-time monitoring and control:

• Visual agent management
• Memory browser with search
• Task queue visualization
• Live WebSocket updates
• React 18 + Material-UI
• Dark mode support

🔌 6 LLM Providers

Choose your preferred AI:

• Anthropic - Claude Sonnet 4 (recommended)
• OpenAI - GPT-4o + embeddings
• Ollama - Local models (llama3.2)
• ClaudeCode CLI - Direct Claude Code integration
• Gemini CLI - Google Gemini 2.0
• Codex - GitHub Codex

🔐 Security & Auth

Production-ready security:

• JWT authentication
• BCrypt password hashing
• Role-based access control (Admin, Developer, Viewer)
• Security Auditor agent for code review

📚 Documentation

• GitHub Wiki - Comprehensive user guide (54 pages)

  • Getting Started tutorials
  • Agent guides for all 11 types
  • MCP tools reference
  • Practical recipes and examples
  • Advanced topics (plugins, custom agents, workflows)
  • Complete API reference

• Technical Docs - Architecture and implementation details

  • API.md - MCP tools and programmatic API
  • ARCHITECTURE.md - System architecture
  • DATA.md - Database schemas
  • SECURITY.md - Security model
  • ONBOARDING.md - Developer guide

🚀 Quick Start

Installation

npm install @blackms/aistack

Initialize & Connect to Claude Code

# Initialize project structure
npx @blackms/aistack init

# Add to Claude Code MCP
claude mcp add aistack -- npx @blackms/aistack mcp start

# Verify installation
npx @blackms/aistack status

Start Web Dashboard

# Start backend + web dashboard
npx @blackms/aistack web start

# Open http://localhost:3001

Configuration

Create aistack.config.json in your project root:

{
  "version": "1.5.0",
  "providers": {
    "default": "anthropic",
    "anthropic": {
      "apiKey": "${ANTHROPIC_API_KEY}",
      "model": "claude-sonnet-4-20250514"
    },
    "openai": {
      "apiKey": "${OPENAI_API_KEY}",
      "model": "gpt-4o"
    },
    "ollama": {
      "baseUrl": "http://localhost:11434",
      "model": "llama3.2"
    }
  },
  "memory": {
    "path": "./data/aistack.db",
    "vectorSearch": {
      "enabled": false,
      "provider": "openai"
    }
  },
  "driftDetection": {
    "enabled": false,
    "threshold": 0.95,
    "warningThreshold": 0.8,
    "ancestorDepth": 3,
    "behavior": "warn",
    "asyncEmbedding": true
  },
  "resourceExhaustion": {
    "enabled": false,
    "thresholds": {
      "maxFilesAccessed": 50,
      "maxApiCalls": 100,
      "maxSubtasksSpawned": 20,
      "maxTimeWithoutDeliverableMs": 1800000,
      "maxTokensConsumed": 500000
    },
    "warningThresholdPercent": 0.7,
    "checkIntervalMs": 10000,
    "autoTerminate": false,
    "pauseOnIntervention": true
  },
  "auth": {
    "enabled": true,
    "jwtSecret": "${JWT_SECRET}"
  }
}

💡 Usage Examples

Example 1: Code Generation with Review

Via Claude Code (MCP):

In Claude Code, just ask:
"Use aistack to generate a REST API for user authentication with adversarial review"

aistack will:
1. Spawn a coder agent to write the API
2. Spawn an adversarial agent to find vulnerabilities
3. Fix issues iteratively (up to 3 rounds)
4. Return production-ready code

Via CLI:

# Start adversarial review loop
npx @blackms/aistack workflow run adversarial-review \
  --task "Create REST API for user authentication"

# Check the review status
npx @blackms/aistack agent list

Via TypeScript:

import { createReviewLoop, getConfig } from '@blackms/aistack';

const result = await createReviewLoop(
  'Create REST API for user authentication',
  getConfig(),
  { maxIterations: 3 }
);

console.log(result.finalVerdict); // APPROVED
console.log(result.currentCode);   // Production-ready code

Example 2: Build Institutional Knowledge

Store patterns as you learn:

# Store a coding pattern
npx @blackms/aistack memory store \
  -k "api:error-handling" \
  -c "Always return { success: boolean, data?, error? } structure" \
  -n "best-practices"

# Store an architecture decision
npx @blackms/aistack memory store \
  -k "db:connection" \
  -c "Use connection pooling with max 10 connections" \
  -n "architecture"

Search when you need it:

# Find all patterns about error handling
npx @blackms/aistack memory search -q "error handling" -n "best-practices"

# Find architecture decisions about databases
npx @blackms/aistack memory search -q "database" -n "architecture"

In Claude Code:

You: "What's our pattern for API error handling?"
Claude uses memory_search tool: Returns your stored pattern
Claude: "Based on your team's pattern, use { success, data, error } structure"

Example 3: Multi-Agent Collaboration

Generate feature with tests and docs:

import { spawnAgent, getMemoryManager, getConfig } from '@blackms/aistack';

// 1. Coder writes the feature
const coder = spawnAgent('coder', { name: 'feature-coder' });
const code = await executeTask(coder, 'Create user profile API');

// 2. Tester writes tests
const tester = spawnAgent('tester', { name: 'test-writer' });
const tests = await executeTask(tester, 'Write tests for user profile API');

// 3. Documentation agent generates docs
const docs = spawnAgent('documentation', { name: 'doc-writer' });
const documentation = await executeTask(docs, 'Document user profile API');

// 4. Store the pattern for future use
const memory = getMemoryManager(getConfig());
await memory.store('pattern:user-api', 'User API pattern with tests and docs', {
  namespace: 'patterns',
  metadata: { code, tests, documentation }
});

Example 4: Use in Claude Code

After installing the MCP server:

claude mcp add aistack -- npx @blackms/aistack mcp start

In Claude Code, you can:

"Spawn a researcher agent to analyze this codebase"
→ Uses agent_spawn tool

"Store this pattern in memory: Always validate user input"
→ Uses memory_store tool

"Search memory for authentication patterns"
→ Uses memory_search tool

"Start an adversarial review of this function"
→ Uses review_loop_start tool

"List all active agents"
→ Uses agent_list tool

Example 5: CLI Workflow

# 1. Start a session
npx @blackms/aistack session start --metadata '{"project": "myapp"}'

# 2. Spawn specialized agents
npx @blackms/aistack agent spawn -t coder -n backend-coder
npx @blackms/aistack agent spawn -t tester -n test-writer
npx @blackms/aistack agent spawn -t reviewer -n code-reviewer

# 3. Run tasks (agents process automatically)
npx @blackms/aistack agent run -t coder -p "Create login endpoint"
npx @blackms/aistack agent run -t tester -p "Test login endpoint"
npx @blackms/aistack agent run -t reviewer -p "Review login code"

# 4. Check system status
npx @blackms/aistack status

# 5. End session
npx @blackms/aistack session end

Example 6: Web Dashboard

# Start the dashboard
npx @blackms/aistack web start

Then open http://localhost:3001 to:

• 👀 Monitor all active agents in real-time
• 🧠 Browse and search your memory database
• ✅ Manage tasks and workflows visually
• 📊 View system health and statistics
• 🔄 Watch adversarial review loops in progress

📦 MCP Tools

Agent Tools (6)

Memory Tools (5)

Identity Tools (8)

Task Tools (8)

Session Tools (4)

System Tools (3)

GitHub Tools (7)

Total: 41 MCP Tools

Note: Review loop functionality is available via the programmatic API (createReviewLoop) and CLI, but not exposed as MCP tools.

💻 Programmatic API

TypeScript SDK

import {
  spawnAgent,
  getMemoryManager,
  startMCPServer,
  getConfig,
  createReviewLoop,
} from '@blackms/aistack';

// Spawn an agent
const agent = spawnAgent('coder', {
  name: 'my-coder',
  metadata: { project: 'awesome-app' }
});

// Use memory with FTS5 search
const memory = getMemoryManager(getConfig());
await memory.store('architecture:pattern', 'Use dependency injection', {
  namespace: 'best-practices',
  tags: ['architecture', 'patterns'],
});

const results = await memory.search('dependency injection');
console.log(results); // FTS5 ranked results

// Start adversarial review loop
const reviewState = await createReviewLoop(
  'Write a secure authentication function',
  getConfig(),
  { maxIterations: 3 }
);

console.log(reviewState.finalVerdict); // APPROVED or REJECTED
console.log(reviewState.currentCode);
console.log(reviewState.reviews); // All review rounds

// Start MCP server
const server = await startMCPServer(getConfig());
console.log('MCP server listening on stdio');

Submodule Imports

import { MemoryManager } from '@blackms/aistack/memory';
import { spawnAgent, listAgentTypes, pauseAgent, resumeAgent } from '@blackms/aistack/agents';
import { startMCPServer } from '@blackms/aistack/mcp';
import { getResourceExhaustionService } from '@blackms/aistack/monitoring';

// Direct imports for smaller bundles
const agentTypes = listAgentTypes();
// => ['coder', 'researcher', 'tester', 'reviewer', 'adversarial', 'architect', 'coordinator', 'analyst', 'devops', 'documentation', 'security-auditor']

📂 Project Structure

aistack/
├── src/
│   ├── agents/          # 11 agent types with system prompts + identity service
│   ├── mcp/             # MCP server + 41 tools
│   ├── memory/          # SQLite + FTS5 + vector search
│   ├── tasks/           # Drift detection service
│   ├── monitoring/      # Resource exhaustion, metrics, health
│   ├── coordination/    # Task queue, message bus, review loop
│   ├── web/             # REST API + WebSocket server + identity routes
│   ├── providers/       # 6 LLM provider integrations
│   ├── workflows/       # Multi-phase workflow engine
│   ├── auth/            # JWT + RBAC authentication
│   ├── github/          # GitHub issues/PRs integration
│   ├── plugins/         # Plugin system
│   ├── hooks/           # Lifecycle hooks
│   └── cli/             # Command-line interface
│
├── web/                 # React 18 dashboard
│   └── src/
│       ├── pages/       # 11 dashboard pages
│       ├── components/  # React components
│       └── stores/      # Zustand state management
│
├── migrations/          # Database migrations
├── tests/               # Unit + integration tests
├── docs/                # Technical documentation
└── .github/workflows/   # CI/CD pipeline

🧪 Development & Testing

Build & Test

npm install               # Install dependencies
npm run build             # Build TypeScript to dist/
npm test                  # Run all tests (unit + integration)
npm run test:unit         # Unit tests only
npm run test:integration  # Integration tests only
npm run test:coverage     # Generate coverage report
npm run typecheck         # Type check without emit
npm run lint              # ESLint

CI/CD Pipeline

GitHub Actions workflow with 5 parallel jobs:

1. Lint - ESLint code quality checks
2. Typecheck - TypeScript type validation
3. Unit Tests - Fast isolated tests
4. Integration Tests - Database + agent integration
5. Build - Production build verification

Code Coverage: Uploaded to Codecov after test completion

Code: .github/workflows/ci.yml

Web Dashboard Development

npm run dev:web           # Start Vite dev server (hot reload)
npm run build:web         # Build for production

⚠️ What aistack Does NOT Include

To set accurate expectations, here are features explicitly not implemented:

• ❌ Docker containerization (no Dockerfile in project root)
• ❌ Kubernetes/Helm manifests (no orchestration configs)
• ❌ Cloud-specific deployments (AWS, GCP, Azure templates)
• ❌ GraphQL API (REST + WebSocket only)
• ❌ Multi-tenancy (single SQLite instance per deployment)
• ❌ Built-in monitoring/observability (no Prometheus/Grafana)
• ❌ Message queue systems (no Kafka, RabbitMQ, Redis Streams)
• ❌ Distributed tracing (no OpenTelemetry integration)

aistack is designed as a local-first, NPM-distributed package for developer workflows, not cloud-native microservices.

🗺️ Roadmap

_{Roadmap items are planned features, not current capabilities.}

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing)
5. Open a Pull Request

PR Requirements:

• All tests pass (npm test)
• Code linted (npm run lint)
• Type checked (npm run typecheck)
• Build succeeds (npm run build)
• Code coverage maintained or improved

📄 License

MIT © 2024