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
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:
- Spawn specialized agents - Each agent has specific expertise (coding, testing, reviewing, etc.)
- They communicate through a message bus - Agents can coordinate and share information
- Memory persists across sessions - Agents remember patterns, decisions, and learnings
- Adversarial validation - Code is automatically reviewed and improved through iterative feedback
- 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
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
|
Node.js 20+ |
TypeScript |
SQLite + FTS5 |
Vitest |
|
React 18 |
Material-UI |
Vite |
Anthropic |
|
OpenAI |
Ollama |
GitHub Actions |
NPM Package |
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
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
Automatic code improvement through iterative feedback:
- Coder agent generates code
- Adversarial agent reviews and tries to break it
- Coder fixes issues
- Repeat up to 3 times until approved
Result: More robust, secure code with fewer bugs.
Persistent agent identities with lifecycle management:
- Stable UUIDs - Agents have persistent
agent_idacross 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
Detect when task descriptions are semantically similar to ancestors:
- Embedding-based Similarity - Uses OpenAI or Ollama embeddings
- Configurable Thresholds -
threshold(block/warn) andwarningThreshold(warn only) - Two Behaviors -
warn(log and allow) orprevent(block creation) - Task Relationships - Track
parent_of,derived_from,depends_on,supersedes - Metrics & Events - Full logging for drift detection analysis
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
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, orhumanreviewers - Configurable Risk Estimation - Define high/medium risk agent types and keyword patterns
- Task Depth Tracking - Prevent unbounded task recursion with
maxDepthlimits - Checkpoint Lifecycle -
pendingβapproved/rejected/expiredwith audit trail - Timeout & Auto-Expiry - Checkpoints expire after configurable timeout
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)
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
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
Production-ready security:
- JWT authentication
- BCrypt password hashing
- Role-based access control (Admin, Developer, Viewer)
- Security Auditor agent for code review
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
-
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
npm install @blackms/aistack# 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 backend + web dashboard
npx @blackms/aistack web start
# Open http://localhost:3001Create 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"]
}
}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 listVia 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 codeStore 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"
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 }
});After installing the MCP server:
claude mcp add aistack -- npx @blackms/aistack mcp startIn 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
# 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# Start the dashboard
npx @blackms/aistack web startThen 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
| Tool | Description | Input | Code |
|---|---|---|---|
agent_spawn |
Spawn a new agent | { type, name?, sessionId?, metadata? } |
/src/mcp/tools/agent-tools.ts:45 |
agent_list |
List active agents | { sessionId? } |
/src/mcp/tools/agent-tools.ts:90 |
agent_stop |
Stop an agent | { id?, name? } |
/src/mcp/tools/agent-tools.ts:117 |
agent_status |
Get agent status | { id?, name? } |
/src/mcp/tools/agent-tools.ts:144 |
agent_types |
List available agent types | {} |
/src/mcp/tools/agent-tools.ts:188 |
agent_update_status |
Update agent status | { id, status } |
/src/mcp/tools/agent-tools.ts:214 |
| Tool | Description | Input | Code |
|---|---|---|---|
memory_store |
Store memory entry | { key, content, namespace?, metadata?, agentId? } |
/src/mcp/tools/memory-tools.ts:48 |
memory_search |
Search with FTS5 | { query, namespace?, limit?, agentId?, includeShared? } |
/src/mcp/tools/memory-tools.ts:94 |
memory_get |
Get by key | { key, namespace? } |
/src/mcp/tools/memory-tools.ts:145 |
memory_list |
List all entries | { namespace?, limit?, offset?, agentId?, includeShared? } |
/src/mcp/tools/memory-tools.ts:182 |
memory_delete |
Delete entry | { key, namespace? } |
/src/mcp/tools/memory-tools.ts:221 |
| Tool | Description | Input | Code |
|---|---|---|---|
identity_create |
Create agent identity | { agentType, displayName?, capabilities?, metadata? } |
/src/mcp/tools/identity-tools.ts:98 |
identity_get |
Get identity by ID or name | { agentId?, displayName? } |
/src/mcp/tools/identity-tools.ts:155 |
identity_list |
List identities | { status?, agentType?, limit?, offset? } |
/src/mcp/tools/identity-tools.ts:205 |
identity_update |
Update identity metadata | { agentId, displayName?, metadata?, capabilities? } |
/src/mcp/tools/identity-tools.ts:247 |
identity_activate |
Activate identity | { agentId, actorId? } |
/src/mcp/tools/identity-tools.ts:311 |
identity_deactivate |
Deactivate identity | { agentId, reason?, actorId? } |
/src/mcp/tools/identity-tools.ts:342 |
identity_retire |
Retire identity (permanent) | { agentId, reason?, actorId? } |
/src/mcp/tools/identity-tools.ts:378 |
identity_audit |
Get audit trail | { agentId, limit? } |
/src/mcp/tools/identity-tools.ts:414 |
| Tool | Description | Input | Code |
|---|---|---|---|
task_create |
Create task with drift detection | { agentType, input?, sessionId?, parentTaskId?, riskLevel? } |
/src/mcp/tools/task-tools.ts:50 |
task_assign |
Assign task to agent | { taskId, agentId } |
/src/mcp/tools/task-tools.ts:138 |
task_complete |
Mark task complete | { taskId, output?, status? } |
/src/mcp/tools/task-tools.ts:169 |
task_list |
List tasks | { sessionId?, status? } |
/src/mcp/tools/task-tools.ts:206 |
task_get |
Get task details | { taskId } |
/src/mcp/tools/task-tools.ts:236 |
task_check_drift |
Check for semantic drift | { taskInput, taskType, parentTaskId? } |
/src/mcp/tools/task-tools.ts:273 |
task_get_relationships |
Get task relationships | { taskId, direction? } |
/src/mcp/tools/task-tools.ts:328 |
task_drift_metrics |
Get drift detection metrics | { since? } |
/src/mcp/tools/task-tools.ts:376 |
| Tool | Description | Input | Code |
|---|---|---|---|
consensus_check |
Check if consensus required | { agentType, input?, parentTaskId?, riskLevel? } |
/src/mcp/tools/task-tools.ts:504 |
consensus_list_pending |
List pending checkpoints | { limit?, offset? } |
/src/mcp/tools/task-tools.ts:560 |
consensus_get |
Get checkpoint details | { checkpointId } |
/src/mcp/tools/task-tools.ts:610 |
consensus_approve |
Approve a checkpoint | { checkpointId, reviewedBy, feedback? } |
/src/mcp/tools/task-tools.ts:670 |
consensus_reject |
Reject a checkpoint | { checkpointId, reviewedBy, feedback?, rejectedSubtaskIds? } |
/src/mcp/tools/task-tools.ts:720 |
| Tool | Description | Input | Code |
|---|---|---|---|
session_start |
Start new session | { metadata? } |
/src/mcp/tools/session-tools.ts:23 |
session_end |
End session | { sessionId } |
/src/mcp/tools/session-tools.ts:56 |
session_status |
Get session status | { sessionId } |
/src/mcp/tools/session-tools.ts:85 |
session_active |
List active sessions | {} |
/src/mcp/tools/session-tools.ts:138 |
| Tool | Description | Input | Code |
|---|---|---|---|
system_status |
Get system status | {} |
/src/mcp/tools/system-tools.ts:12 |
system_health |
Health check | {} |
/src/mcp/tools/system-tools.ts:52 |
system_config |
Get config | {} |
/src/mcp/tools/system-tools.ts:131 |
| Tool | Description | Input | Code |
|---|---|---|---|
github_issue_create |
Create issue | { owner, repo, title, body } |
/src/mcp/tools/github-tools.ts:94 |
github_issue_list |
List issues | { owner, repo, state? } |
/src/mcp/tools/github-tools.ts:137 |
github_issue_get |
Get issue | { owner, repo, number } |
/src/mcp/tools/github-tools.ts:170 |
github_pr_create |
Create PR | { owner, repo, title, body, head, base } |
/src/mcp/tools/github-tools.ts:198 |
github_pr_list |
List PRs | { owner, repo, state? } |
/src/mcp/tools/github-tools.ts:240 |
github_pr_get |
Get PR | { owner, repo, number } |
/src/mcp/tools/github-tools.ts:273 |
github_repo_info |
Get repo info | { owner, repo } |
/src/mcp/tools/github-tools.ts:301 |
Total: 46 MCP Tools
Note: Review loop functionality is available via the programmatic API (
createReviewLoop) and CLI, but not exposed as MCP tools.
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');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']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
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 # ESLintGitHub Actions workflow with 5 parallel jobs:
- Lint - ESLint code quality checks
- Typecheck - TypeScript type validation
- Unit Tests - Fast isolated tests
- Integration Tests - Database + agent integration
- Build - Production build verification
Code Coverage: Uploaded to Codecov after test completion
Code: .github/workflows/ci.yml
npm run dev:web # Start Vite dev server (hot reload)
npm run build:web # Build for productionTo set accurate expectations, here are features explicitly not implemented:
- β Docker containerization (no
Dockerfilein 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)
β οΈ Limited observability - Built-in health checks and Prometheus-style metrics, but no Grafana dashboards- β 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.
aistack is feature-complete for its primary use case: local Claude Code integration with multi-agent orchestration.
Current focus areas:
- Stability and bug fixes
- Documentation improvements
- Community-requested features
Have an idea? Open an issue or join our Discord
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing) - Commit changes (
git commit -m 'Add amazing feature') - Push to branch (
git push origin feature/amazing) - 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
MIT Β© 2024
Wiki Β· Documentation Β· Issues Β· Discussions Β· NPM Package
Built with TypeScript Β· Made for Claude Code Β· Distributed via NPM
β README verified against codebase v1.5.3 - All claims backed by implemented code with file:line references (includes Consensus Checkpoints, Resource Exhaustion Monitoring, and Session-based Memory Isolation)