SwarmCraft

A visual code exploration and multi-agent orchestration platform. SwarmCraft enables developers to visualize codebases as interactive graphs, manage AI agent swarms, and explore code relationships through an intuitive web interface.

Features

Code Visualization

• Interactive Graph Canvas: Visualize code structure as a navigable graph using Sigma.js or Cytoscape.js
• Dual View Modes: Switch between Sigma (fast, WebGL-based) and Cytoscape (feature-rich, DOM-based) renderers
• File Tree Navigation: Browse and navigate the codebase structure
• Code References Panel: View code snippets and relationships for selected nodes

Session Visualization (Cytoscape)

• VoiceTree-inspired Design: Hierarchical agent visualization with conversation flow
• Multi-select & Focus Mode: Select multiple nodes with keyboard modifiers, focus on specific subgraphs
• Undo/Redo History: Track and revert graph changes with full history support
• Viewport Navigation: Zoom, pan, fit-to-view with viewport history (back/forward navigation)
• Theme System: Light/dark/high-contrast themes with custom theme support
• Minimap: Overview navigation for large graphs
• Performance Optimization: Level-of-Detail (LOD) rendering, debounced layouts, batch operations

Multi-Agent Orchestration

• Agent Swarm Management: Create, monitor, and coordinate multiple AI agents via MAP protocol
• ACP Conversations: Interactive conversations with agents (permissions, questions, tool calls)
• Task Assignment: Create and assign tasks to agents
• Real-time Messaging: Monitor inter-agent communication

Code Analysis

• Embeddings Pipeline: Generate code embeddings using WebGPU or WASM
• Semantic Search: Find related code using vector similarity

Tech Stack

• Frontend: React 18, TypeScript, Tailwind CSS
• Graph Libraries: Sigma.js, Cytoscape.js, Graphology
• Database: Kuzu (WASM, frontend), SQLite (backend)
• Code Parsing: Tree-sitter (WASM)
• Backend: Fastify, @multi-agent-protocol/sdk
• Build: Vite

Getting Started

Prerequisites

• Node.js 18+
• npm

Installation

# Install dependencies
npm install

# Start frontend dev server
npm run dev

# Start backend server (in a separate terminal)
npm run dev:server

# Build for production
npm run build

# Run tests
npm test

Usage

1. Load a Repository: Drag and drop a ZIP file or clone from a Git URL
2. Explore the Graph: Navigate the code structure using pan, zoom, and node selection
3. Use Agents: Open the SwarmCraft panel to connect MAP servers and manage AI agents

Project Structure

src/
├── ui/                        # Frontend (React + Vite)
│   ├── components/
│   │   ├── cytoscape/         # Cytoscape visualization components
│   │   │   ├── adapters/      # Data adapters (Graphology, Agent)
│   │   │   ├── services/      # Core services (Selection, Navigation, History, Theme, Performance)
│   │   │   └── hooks/         # React hooks for Cytoscape integration
│   │   ├── agents/            # Agent management UI
│   │   ├── acp/               # ACP conversation panels
│   │   ├── swarmcraft/        # SwarmCraft dashboard components
│   │   └── ...                # Other UI components
│   ├── core/
│   │   ├── embeddings/        # Code embedding generation
│   │   ├── graph/             # Graph operations and algorithms
│   │   ├── ingestion/         # Code ingestion pipeline
│   │   ├── kuzu/              # Kuzu database integration
│   │   ├── mcp/               # MCP client implementation
│   │   └── search/            # Search functionality
│   ├── hooks/                 # Shared React hooks
│   ├── services/              # API client, WS client, ACP service
│   └── types/                 # TypeScript type definitions
├── server/                    # Backend (Fastify)
│   ├── routes/                # REST API endpoints
│   ├── map/                   # MAP protocol integration
│   ├── websocket/             # WebSocket hub
│   ├── db/                    # SQLite persistence
│   ├── subprocess/            # Process management
│   └── terminal/              # PTY management

Testing

The project uses Vitest for testing.

npm test                       # Run all tests once
npm run test:ui:watch          # UI tests in watch mode
npm run test:server:watch      # Server tests in watch mode
npm run test:coverage          # With coverage report

Test Structure

• Tests are co-located with source files in __tests__ directories
• Mock helpers are in src/ui/components/cytoscape/__tests__/helpers/
• Global test setup is in src/ui/test/setup.ts

Environment Variables

| Variable | Default | Purpose | |----------|---------|---------| | VITE_SWARMCRAFT_API_URL | http://localhost:3001/api | Backend API URL | | VITE_SWARMCRAFT_WS_URL | ws://localhost:3001/ws | Backend WebSocket URL |

License

MIT