aistack

Ultra-Modern Multi-Agent Orchestration for Claude Code

Production-grade agent orchestration with adversarial validation, persistent memory, and real-time web dashboard.

Quick Start · What It Does · Features · Documentation

11 agents · 46 MCP tools · 6 LLM providers · SQLite + FTS5 · Web dashboard · Agent Identity · Drift Detection · Consensus Checkpoints · Resource 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

🤝 Consensus Checkpoints

Require validation before high-risk tasks can spawn subtasks:

• Risk-Based Gating - Configure which risk levels (high, medium, low) require consensus
• Reviewer Strategies - Choose from adversarial, different-model, or human reviewers
• Configurable Risk Estimation - Define high/medium risk agent types and keyword patterns
• Task Depth Tracking - Prevent unbounded task recursion with maxDepth limits
• Checkpoint Lifecycle - pending → approved/rejected/expired with audit trail
• Timeout & Auto-Expiry - Checkpoints expire after configurable timeout

🎯 46 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 - 13 task tools (create, assign, complete, list, get, check_drift, get_relationships, drift_metrics, + 5 consensus tools) - 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

📢 Slack Integration

Real-time notifications to your team: - Agent Events - Spawning, stopping, errors - Workflow Updates - Start, completion, failures - Review Loop Progress - Iteration updates - Resource Alerts - Warnings, interventions, terminations - Customizable - Choose which events to notify

---

📚 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.3",
  "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,
    "requireConfirmationOnIntervention": true,
    "pauseOnIntervention": true
  },
  "slack": {
    "enabled": false,
    "webhookUrl": "${SLACK_WEBHOOK_URL}",
    "channel": "#aistack-notifications",
    "notifyOnAgentSpawn": false,
    "notifyOnWorkflowComplete": true,
    "notifyOnErrors": true,
    "notifyOnReviewLoop": true,
    "notifyOnResourceWarning": true,
    "notifyOnResourceIntervention": true
  },
  "consensus": {
    "enabled": false,
    "requireForRiskLevels": ["high", "medium"],
    "reviewerStrategy": "adversarial",
    "timeout": 300000,
    "maxDepth": 5,
    "autoReject": false,
    "highRiskAgentTypes": ["coder", "devops", "security-auditor"],
    "mediumRiskAgentTypes": ["architect", "coordinator", "analyst"],
    "highRiskPatterns": ["delete", "remove", "drop", "deploy", "production", "credentials", "secret", "password", "token", "api key"],
    "mediumRiskPatterns": ["modify", "update", "change", "configure", "install"]
  }
}

---

💡 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: ```bash

Start adversarial review loop

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

Check the review status

npx