@blackms/aistack
Advanced tools
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:
How it works:
Perfect for:
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:
Knowledge that survives across sessions:
Automatic code improvement through iterative feedback:
Result: More robust, secure code with fewer bugs.
Persistent agent identities with lifecycle management:
agent_id across executionscreated → active → dormant → retiredDetect when task descriptions are semantically similar to ancestors:
threshold (block/warn) and warningThreshold (warn only)warn (log and allow) or prevent (block creation)parent_of, derived_from, depends_on, supersedesDetect and prevent runaway agents consuming excessive resources:
normal → warning → intervention → terminationRequire validation before high-risk tasks can spawn subtasks:
adversarial, different-model, or human reviewersmaxDepth limitspending → approved/rejected/expired with audit trailControl aistack directly from Claude Code IDE:
Real-time monitoring and control:
Choose your preferred AI:
Production-ready security:
Real-time notifications to your team:
GitHub Wiki - Comprehensive user guide (54 pages)
Technical Docs - Architecture and implementation details
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:3001
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"]
}
}
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
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"
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 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
# 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 start
Then open http://localhost:3001 to:
| 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 # ESLint
GitHub Actions workflow with 5 parallel jobs:
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 production
To set accurate expectations, here are features explicitly not implemented:
Dockerfile in project root)aistack is designed as a local-first, NPM-distributed package for developer workflows, not cloud-native microservices.
| Priority | Feature | Status |
|---|---|---|
| P1 | HTTP transport for MCP server | Planned |
| P1 | Streaming responses (SSE) | Planned |
| P2 | Agent state persistence to SQLite | Planned |
| P2 | Built-in workflow templates | Planned |
| P3 | Enhanced dashboard analytics | Planned |
| P3 | Metrics and observability hooks | Planned |
| P3 | Docker support (optional) | Under consideration |
Roadmap items are planned features, not current capabilities.
git checkout -b feature/amazing)git commit -m 'Add amazing feature')git push origin feature/amazing)PR Requirements:
npm test)npm run lint)npm run typecheck)npm run build)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)
FAQs
Clean agent orchestration for Claude Code
The npm package @blackms/aistack receives a total of 56 weekly downloads. As such, @blackms/aistack popularity was classified as not popular.
We found that @blackms/aistack demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
Two Joyfill npm beta releases contain an import-time implant that uses blockchain transactions to retrieve a remote-access trojan.
Security News
Socket releases free Certified Patches for high-severity Nuxt vulnerabilities, including server-side remote code execution through server island props.
Security News
An open letter signed by 50 companies, from NVIDIA and Microsoft to Mistral and Hugging Face, urges Washington not to restrict open weight AI.