@blackms/aistack

aistack

Multi-Agent Orchestration for Claude Code

Production-ready agent orchestration with persistent memory and MCP integration.

Get Started · Architecture · API Reference · Documentation

Why aistack?

Coordinate specialized AI agents through Claude Code with persistent context, hierarchical task management, and seamless extensibility.

7 agents · 30 MCP tools · 3 LLM providers · SQLite + FTS5 · Plugin system

Tech Stack

Node.js 20+

TypeScript

SQLite

Anthropic

OpenAI

Ollama

Features

Feature	Description
Specialized Agents	7 built-in agent types: coder, researcher, tester, reviewer, architect, coordinator, analyst
Persistent Memory	SQLite with FTS5 full-text search and optional vector embeddings
MCP Integration	30 tools exposed via Model Context Protocol for Claude Code
Hierarchical Coordination	Task queue, message bus, and coordinator pattern
Multi-Provider Support	Anthropic, OpenAI, and Ollama with unified interface
Plugin System	Runtime extensibility for agents, tools, hooks, and providers
Workflow Engine	Multi-phase workflows with adversarial validation

Quick Start

Installation

npm install @blackms/aistack

Initialize & Connect

# Initialize project
npx @blackms/aistack init

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

# Verify installation
npx @blackms/aistack status

Configuration

Create aistack.config.json:

{
  "version": "1.0.0",
  "providers": {
    "default": "anthropic",
    "anthropic": { "apiKey": "${ANTHROPIC_API_KEY}" }
  },
  "memory": {
    "path": "./data/aistack.db",
    "vectorSearch": { "enabled": false }
  }
}

Architecture

graph TB
    subgraph "Claude Code"
        CC[Claude Code IDE]
    end

    subgraph "aistack"
        MCP["MCP Server<br/><small>stdio transport</small>"]

        subgraph Core["Core Services"]
            AM[Agent Manager]
            MM[Memory Manager]
            TQ[Task Queue]
            MB[Message Bus]
        end

        subgraph Agents["Agent Pool"]
            direction LR
            A1[Coder]
            A2[Tester]
            A3[Reviewer]
            A4[Architect]
            A5[Researcher]
            A6[Coordinator]
            A7[Analyst]
        end

        subgraph Storage["Persistence"]
            SQL[(SQLite)]
            FTS[FTS5 Index]
            VEC[Vector Store]
        end

        subgraph Providers["LLM Providers"]
            ANT[Anthropic]
            OAI[OpenAI]
            OLL[Ollama]
        end
    end

    CC <-->|"MCP Protocol"| MCP
    MCP --> AM & MM
    AM --> TQ --> MB
    MB --> A1 & A2 & A3 & A4 & A5 & A6 & A7
    MM --> SQL --> FTS & VEC
    AM -.-> ANT & OAI & OLL

Request Flow

sequenceDiagram
    participant CC as Claude Code
    participant MCP as MCP Server
    participant AM as Agent Manager
    participant MM as Memory
    participant DB as SQLite

    CC->>MCP: agent_spawn("coder")
    MCP->>AM: spawnAgent("coder")
    AM-->>MCP: SpawnedAgent
    MCP-->>CC: { id, type, status }

    CC->>MCP: memory_store(key, content)
    MCP->>MM: store(key, content)
    MM->>DB: INSERT/UPDATE
    DB-->>MM: MemoryEntry
    MM-->>MCP: { success: true }
    MCP-->>CC: { entry }

    CC->>MCP: memory_search(query)
    MCP->>MM: search(query)
    MM->>DB: FTS5 MATCH
    DB-->>MM: Results
    MM-->>MCP: SearchResults
    MCP-->>CC: { results }

Agents

Agent	Purpose	Capabilities
coder	Write and modify code	write-code edit-code refactor debug implement-features
researcher	Gather information	search-code read-documentation analyze-patterns gather-requirements explore-codebase
tester	Test and validate	write-tests run-tests identify-edge-cases coverage-analysis test-debugging
reviewer	Quality assurance	code-review security-review performance-review best-practices feedback
architect	System design	system-design technical-decisions architecture-review documentation trade-off-analysis
coordinator	Orchestrate work	task-decomposition agent-coordination progress-tracking result-synthesis workflow-management
analyst	Data insights	data-analysis performance-profiling metrics-collection trend-analysis reporting

MCP Tools

Agent Tools (6)

agent_spawn          agent_list           agent_stop
agent_status         agent_types          agent_update_status

Memory Tools (5)

memory_store         memory_search        memory_get
memory_list          memory_delete

Task Tools (5)

task_create          task_assign          task_complete
task_list            task_get

Session Tools (4)

session_start        session_end          session_status
session_active

System Tools (3)

system_status        system_health        system_config

GitHub Tools (7)

github_issue_create  github_issue_list    github_issue_get
github_pr_create     github_pr_list       github_pr_get
github_repo_info

Programmatic API

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

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

// Use memory with search
const memory = getMemoryManager(getConfig());
await memory.store('pattern', 'Use dependency injection', {
  namespace: 'architecture'
});
const results = await memory.search('injection');

// Start MCP server
const server = await startMCPServer(getConfig());

Submodule Imports

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

Plugin System

Extend aistack with custom agents, tools, and hooks:

import type { AgentStackPlugin } from '@blackms/aistack';

export default {
  name: 'my-plugin',
  version: '1.0.0',

  agents: [{
    type: 'custom-agent',
    name: 'Custom Agent',
    description: 'Specialized behavior',
    systemPrompt: 'You are a custom agent...',
    capabilities: ['custom-task'],
  }],

  tools: [{
    name: 'custom_tool',
    description: 'A custom MCP tool',
    inputSchema: { type: 'object', properties: { input: { type: 'string' } } },
    handler: async (params) => ({ result: 'done' })
  }],

  async init(config) { /* setup */ },
  async cleanup() { /* teardown */ }
} satisfies AgentStackPlugin;

CLI Reference

Command	Description
init	Initialize project structure
agent spawn -t <type>	Spawn agent
agent list	List active agents
agent stop -n <name>	Stop agent
agent types	Show available types
agent status -n <name>	Get agent status
agent run -t <type> -p <prompt>	Spawn and execute task
agent exec -n <name> -p <prompt>	Execute task with existing agent
memory store -k <key> -c <content>	Store entry
memory search -q <query>	Search memory
memory list	List entries
memory delete -k <key>	Delete entry
mcp start	Start MCP server
mcp tools	List MCP tools
workflow run <name>	Run workflow
workflow list	List workflows
status	System status

LLM Providers

API Providers

Provider	Default Model	Embeddings
Anthropic	claude-sonnet-4-20250514	-
OpenAI	gpt-4o	text-embedding-3-small
Ollama	llama3.2	nomic-embed-text

CLI Providers

Provider	CLI Tool	Default Model
Claude Code	claude	sonnet
Gemini CLI	gemini	gemini-2.0-flash
Codex	codex	-

CLI providers enable agent execution through external CLI tools, useful for interactive workflows.

Project Structure

src/
├── agents/         # Agent registry, spawner, definitions
├── cli/            # CLI commands
├── coordination/   # Task queue, message bus, topology
├── github/         # GitHub integration
├── hooks/          # Lifecycle hooks
├── mcp/            # MCP server and 30 tools
├── memory/         # SQLite, FTS5, vector search
├── plugins/        # Plugin loader and registry
├── providers/      # LLM provider implementations
├── workflows/      # Workflow engine
└── utils/          # Config, logger, validation

Development

npm install          # Install dependencies
npm run build        # Build
npm test             # Run tests
npm run test:coverage # With coverage
npm run typecheck    # Type check
npm run lint         # Lint

Roadmap

Priority	Feature
P1	HTTP transport for MCP server
P1	Streaming responses
P2	Agent state persistence
P2	Built-in workflow templates
P3	Web dashboard
P3	Metrics and observability

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

Contributing

• 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

All PRs must pass CI (tests, lint, typecheck, build).

License

MIT © 2024

Documentation · Issues · Discussions

_{Built with TypeScript · Made for Claude Code}