Why aistack?

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

7 agents · 30 MCP tools · 6 LLM providers · SQLite + FTS5 · Web dashboard · Plugin system

Tech Stack

Node.js 20+	TypeScript	SQLite + FTS5	React 18
Anthropic	OpenAI	Ollama	Vite

Features

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

Start Web Dashboard

# Start backend + web dashboard
npx @blackms/aistack web start

# Open http://localhost:3001

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 Clients["Client Layer"]
        CC[Claude Code IDE]
        CLI[CLI]
        WEB[Web Dashboard]
    end

    subgraph "aistack"
        MCP["MCP Server<br/><small>stdio transport</small>"]
        HTTP["HTTP Server<br/><small>REST API</small>"]
        WS["WebSocket<br/><small>Real-time events</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/stdio"| MCP
    CLI <-->|"HTTP"| HTTP
    WEB <-->|"HTTP + WS"| HTTP & WS

    MCP & HTTP --> AM & MM
    WS --> MB
    AM --> TQ --> MB
    MB --> A1 & A2 & A3 & A4 & A5 & A6 & A7
    MM --> SQL --> FTS & VEC
    AM -.-> ANT & OAI & OLL

Deployment Overview

C4Deployment
    title Deployment Diagram - Local Machine

    Deployment_Node(local, "Local Machine", "Developer Workstation") {
        Deployment_Node(npm, "npm", "Node.js 20+") {
            Container(aistack, "aistack", "TypeScript", "MCP Server + HTTP Server + WebSocket")
            ContainerDb(sqlite, "SQLite", "better-sqlite3", "Memory + FTS5 + Vector")
        }
        Deployment_Node(browser, "Browser", "Chrome/Firefox/Safari") {
            Container(dashboard, "Web Dashboard", "React 18 + Vite", "Management UI")
        }
        Deployment_Node(ide, "IDE", "VS Code") {
            Container(claude, "Claude Code", "Extension", "AI Assistant")
        }
    }

    Deployment_Node(cloud, "Cloud Services", "External") {
        Container(anthropic, "Anthropic API", "HTTPS", "Claude models")
        Container(openai, "OpenAI API", "HTTPS", "GPT models")
        Container(ollama_remote, "Ollama", "Local/Remote", "Local LLMs")
    }

    Rel(claude, aistack, "MCP/stdio")
    Rel(dashboard, aistack, "HTTP + WebSocket")
    Rel(aistack, sqlite, "SQL")
    Rel(aistack, anthropic, "HTTPS")
    Rel(aistack, openai, "HTTPS")
    Rel(aistack, ollama_remote, "HTTP")

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 }

Web Dashboard

The built-in web dashboard provides visual management and real-time monitoring of your agent orchestration.

Starting the Dashboard

# Start the web server (includes dashboard)
npx @blackms/aistack web start

# Open in browser
open http://localhost:3001

Dashboard Pages

Web Dashboard Flow

sequenceDiagram
    participant User as Browser
    participant WS as WebSocket
    participant HTTP as HTTP Server
    participant Core as Core Services
    participant DB as SQLite

    User->>HTTP: GET /api/system/status
    HTTP->>Core: getSystemStatus()
    Core-->>HTTP: SystemStatus
    HTTP-->>User: { agents, memory, tasks }

    User->>WS: Connect ws://localhost:3001
    WS-->>User: Connected

    User->>HTTP: POST /api/agents
    HTTP->>Core: spawnAgent("coder")
    Core->>WS: emit("agent:spawned")
    WS-->>User: { event: "agent:spawned", data }
    HTTP-->>User: { agent }

    Note over User,WS: Real-time updates via WebSocket

    Core->>WS: emit("task:completed")
    WS-->>User: { event: "task:completed", data }

Agents

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

LLM Providers

API Providers

CLI Providers

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

Project Structure

src/
├── agents/         # Agent registry, spawner, definitions (7 types)
├── 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 (6 providers)
├── web/            # REST API routes + WebSocket
├── workflows/      # Workflow engine
└── utils/          # Config, logger, validation

web/
├── src/
│   ├── pages/      # 9 dashboard pages
│   ├── components/ # React components
│   ├── hooks/      # Custom React hooks
│   └── stores/     # Zustand state management
└── public/         # Static assets

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

# Web dashboard development
npm run dev:web      # Start Vite dev server for web UI
npm run build:web    # Build web UI for production

Roadmap

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

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing)
5. Open a Pull Request

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

License

MIT © 2024