aistack — Summary

aistack is a production-grade TypeScript multi-agent orchestration framework published as the npm package @blackms/aistack. It ships 11 specialized AI agent types (coordinator, coder, tester, reviewer, architect, adversarial, analyst, researcher, security-auditor, devops, documentation), 46 MCP tools, a React 18 web dashboard at port 3001, and SQLite+FTS5+vector memory — all in a single npm install. The framework's central differentiator is the adversarial validation loop: a dedicated "adversarial reviewer" agent that actively tries to break generated code using predefined attack vectors (injection, race conditions, auth bypass, etc.) before the output is accepted. It supports 6 LLM providers (Anthropic, OpenAI, OpenAI Responses API, Gemini CLI, Codex, and Ollama) and routes different agents to different providers via config, making multi-model deployments first-class. Drift detection and consensus checkpoints are built-in as quality gates separate from the adversarial loop. Compared to seeds: closest to claude-flow in MCP-anchored memory and multi-agent coordination, but aistack adds the explicit adversarial subagent pattern (absent from claude-flow), per-session JWT+RBAC agent identity (unique in the corpus), and a 6-provider multi-model matrix where claude-flow is single-provider.

aistack — Overview

Origin

Created by Alessandro Annini (blackms). First published to npm as @blackms/aistack. Version 1.6.1 at time of analysis. GitHub: https://github.com/blackms/aistack. The project grew out of the premise that single-agent sessions cannot produce production-grade code without adversarial review; the adversarial agent is the central design feature.

Philosophy

From the README: "Production-grade agent orchestration with adversarial validation, persistent memory, and real-time web dashboard." The core mental model is a software development team where:

• The Coordinator breaks down requirements and orchestrates workflow
• Specialized agents (Coder, Tester, Architect, etc.) execute their domain tasks
• The Adversarial agent serves as a hostile critic that actively tries to break what the Coder produced
• Memory persists learnings ("Always use bcrypt for passwords") across sessions

Key design choices

1. Adversarial-first quality: every code generation cycle includes adversarial review before acceptance — not an optional toggle but an architectural requirement
2. Agent identity with JWT/RBAC: each spawned agent has a cryptographic identity token and role, preventing agents from assuming unauthorized capabilities
3. Drift detection: compares agent behavior over time and flags when outputs diverge from expected patterns, acting as an early warning for hallucination drift
4. Consensus checkpoints: multiple agents must agree on a result before moving forward — similar in concept to claude-flow's Raft consensus but implemented in the TypeScript runtime layer

Taglines from README

"Ultra-Modern Multi-Agent Orchestration for Claude Code" "11 agents · 46 MCP tools · 6 LLM providers · SQLite + FTS5 · Web dashboard · Agent Identity · Drift Detection · Consensus Checkpoints · Resource Monitoring"

aistack — Architecture

Distribution

• npm package: @blackms/aistack (v1.6.1)
• Install: npm install @blackms/aistack
• CLI binary: aistack (from bin.aistack in package.json pointing to ./dist/cli/index.js)
• MCP add: claude mcp add aistack -- npx @blackms/aistack mcp start
• Required runtime: Node.js >= 20.0.0

Directory structure (source)

src/
  agents/
    definitions/    # 11 TypeScript agent class files
    identity-service.ts
    registry.ts
    spawner.ts
  cli/
    commands/       # init, agent, mcp, memory, status, web, workflow, plugin, agent-watch
  mcp/
    tools/          # agent-tools, github-tools, identity-tools, memory-tools,
                    # review-loop-tools, session-tools, system-tools, task-tools
  memory/
    sqlite-store.ts
    fts-search.ts
    vector-search.ts
    access-control.ts
  providers/        # anthropic, openai, gemini-cli, codex, ollama (6 total)
  workflows/        # multi-phase workflow engine
  auth/             # JWT + RBAC
  github/           # GitHub issues/PRs
  plugins/          # plugin system
  hooks/            # lifecycle hooks
web/                # React 18 dashboard (Vite + React 18)
data/               # SQLite DB (aistack.db)

Config file

aistack.config.json in project root:

{
  "version": "1.5.3",
  "providers": { "default": "anthropic", ... },
  "memory": { "path": "./data/aistack.db", "vectorSearch": {...} },
  "agents": { "maxConcurrent": 5, "defaultTimeout": 300 },
  "web": { "enabled": true, "port": 3001 },
  "hooks": { "sessionStart": true, "sessionEnd": true, "preTask": true, "postTask": true }
}

Required runtime

• Node.js >= 20.0.0
• TypeScript compiled to ESM
• SQLite (via better-sqlite3 bundled)

Target AI tools

• Claude Code (MCP client)
• Any MCP-compatible client
• Also functions as standalone npm library

LLM Providers

1. Anthropic (claude-sonnet-4-20250514 default)
2. OpenAI (gpt-4o)
3. OpenAI Responses API
4. Gemini CLI
5. Codex
6. Ollama (local, llama3.2 default)

aistack — Components

Agent definitions (11)

CLI commands (10)

MCP tools (46 across 9 modules)

Hooks (lifecycle, 4)

• sessionStart — initialize session state
• sessionEnd — persist session artifacts
• preTask — pre-task validation
• postTask — post-task quality checks

Memory subsystems (3)

• SQLiteStore — primary structured storage (SQLite)
• FTSSearch — full-text search via SQLite FTS5
• VectorSearch — vector similarity search (requires OpenAI embeddings API)

Web dashboard (React 18)

• Vite + React 18 frontend in web/
• Dev port: 5173/5174
• Served by backend at port 3001 via aistack web start

aistack — Uniqueness & Positioning

Differs from seeds

Closest to claude-flow in overall architecture: MCP-anchored toolserver with SQLite memory, hierarchical multi-agent coordination, TypeScript runtime. The key deltas:

1. Adversarial subagent — aistack's defining feature is a dedicated hostile reviewer whose sole purpose is to break generated code. Claude-flow has no adversarial agent; superpowers and spec-driver have adversarial review skills but not a dedicated agent type with its own identity and system prompt.

2. Agent identity + RBAC — JWT-based agent identity (each agent gets a cryptographic identity token scoped to its session and role) prevents unauthorized capability escalation. No other seed framework has this.

3. 6-provider multi-model — aistack allows different agents to use different LLM providers (e.g., adversarial runs on GPT-4o, coder on Claude Sonnet). Claude-flow hardcodes Claude as primary; taskmaster-ai has multi-model but only for named roles (main/research/fallback).

4. Drift detection — periodic comparison of agent output distributions to detect hallucination drift over time. Novel in the corpus.

5. Consensus checkpoints — configurable quorum requirement before phase advancement. Claude-flow has Raft/Byzantine consensus for swarm coordination, but aistack's consensus is at the individual task verification layer.

Observable failure modes

• Vector search requires OpenAI API key even if using Anthropic for agents (embedding dependency)
• maxConcurrent=5 default may bottleneck large task decompositions
• Adversarial loop can become infinite if the coder never satisfies the adversarial agent's criteria (no max-iteration safeguard documented)
• Web dashboard requires the same Node.js process to serve both API and frontend — no independent scaling

Competitive positioning

aistack targets teams wanting automated adversarial review as a quality gate, similar to having a dedicated security red-team member embedded in CI. It is more opinionated about code quality (adversarial gate) and less opinionated about methodology (no SPARC/BMAD equivalent).