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

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

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

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

_{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