claudebench

ClaudeBench 🚀

ClaudeBench is a Redis-first event-driven AI workbench that provides a powerful development platform for Claude and AI agents. Built with a focus on simplicity and performance, it features swarm intelligence for complex task decomposition.

Key Features

• 🔴 Redis-First Architecture: Direct use of Redis primitives for all coordination
• 🐝 Swarm Intelligence: Automatic task decomposition and specialist assignment
• 📡 Event-Driven: JSONRPC 2.0 protocol with real-time WebSocket updates
• 🎨 Modern Web UI: React dashboard with real-time task visualization
• 🔌 MCP Integration: Model Context Protocol support for AI tool integration
• 🚀 High Performance: Built on Bun runtime for maximum speed
• 📊 Real-Time Metrics: Comprehensive monitoring and telemetry

Kanban Board for Tasks (Drag and Drop) with automatic TodoWrite integration

Comprehensive Task details and automatic commit tracking

Refine and generate tasks context for agent execution, or decompose full projects or large tasks

Produce robust task implementation and context guidelines

Track the Events Stream with details

Comprehensive Metrics

🏗️ Architecture

┌─────────────────────────────────────────────────┐
│                  Web Dashboard                  │
│         (React + TanStack + Tailwind)           │
└────────────────────┬────────────────────────────┘
                     │ WebSocket + HTTP
┌────────────────────▼────────────────────────────┐
│              Event Bus (Hono)                   │
│            JSONRPC 2.0 Protocol                 │
└────────┬─────────────────────────┬──────────────┘
         │                         │
┌────────▼──────────┐     ┌───────▼──────────┐
│   Redis Streams   │     │   PostgreSQL     │
│  Pub/Sub + State  │     │  (Persistence)   │
└───────────────────┘     └──────────────────┘
         │
┌────────▼──────────────────────────────────────┐
│         Swarm Intelligence Layer              │
│   (Decomposition, Assignment, Synthesis)      │
└───────────────────────────────────────────────┘

🚀 Quick Start

1. Install Claudebench from this repo
2. Go to your project folder and run bun run {CLAUDEBENCH_FOLDER}/scripts/claudebench-init.ts to onboard your repository
3. Launch claude and say hi, he should carry on and you should be good to use tasking system of claudebench

Prerequisites

• Bun >= 1.2.0 (Install Bun)
• Redis >= 6.0 (Local or Docker)
• PostgreSQL >= 14 (Local or Docker)
• Node.js >= 18 (for some tooling)

Installation

# Clone the repository
git clone https://github.com/fblgit/claudebench.git
cd claudebench

# Install dependencies
bun install

# Copy environment variables
cp .env.example .env
cp apps/server/.env.example apps/server/.env
cp apps/web/.env.example apps/web/.env

# Update .env files with your configuration

Database Setup

# Start PostgreSQL with Docker
bun db:start

# Run database migrations
bun db:push

# (Optional) Open Prisma Studio to view data
bun db:studio

Running the Application

# Start all services (server on :3000, web on :3001)
bun dev

# Or run services individually:
bun dev:server  # Backend server only
bun dev:web     # Frontend only

# Start documentation site (optional, on :3002)
cd docs && bun dev

Running the Event Relay

The event relay provides real-time monitoring of system events:

# Start the relay for monitoring
bun relay

📖 Core Concepts

Event-Driven Architecture

ClaudeBench uses a flat event hierarchy with the pattern domain.action:

// Example events
"task.create"      // Create a new task
"task.complete"    // Mark task as completed
"swarm.decompose"  // Decompose complex task
"system.health"    // System health check

Task States

Tasks progress through these states:

• pending - Awaiting assignment
• in_progress - Currently being worked on
• completed - Successfully finished
• failed - Encountered an error

Swarm Intelligence

Complex tasks are automatically decomposed into subtasks and assigned to specialized workers:

// Create a swarm project
await client.call("swarm.create_project", {
  project: "Build a dashboard with real-time charts",
  constraints: ["Use React", "Include WebSocket updates"],
  priority: 85
});

🔧 API Reference

Task Operations

// Create a task
const task = await client.call("task.create", {
  text: "Process data batch",
  priority: 75,
  metadata: { type: "batch_job" }
});

// Claim a task
const claimed = await client.call("task.claim", {
  workerId: "worker-1",
  maxTasks: 5
});

// Complete a task
await client.call("task.complete", {
  taskId: "t-123",
  workerId: "worker-1",
  result: { processed: 100 }
});

System Operations

// Check system health
const health = await client.call("system.health");

// Get metrics
const metrics = await client.call("system.metrics", {
  detailed: true
});

// Register instance
await client.call("system.register", {
  id: "worker-1",
  roles: ["worker", "observer"]
});

🧪 Testing

# Run all tests
bun test

# Run specific test suites
bun test:contract     # Contract tests
bun test:integration  # Integration tests
bun test:web         # Frontend tests

# Watch mode for development
bun test:watch

📊 Monitoring

ClaudeBench provides comprehensive monitoring capabilities:

• Real-time Dashboard: Visual task tracking at http://localhost:3001
• Event Stream: Live event monitoring via the relay
• Metrics Endpoint: System metrics available via API
• Health Checks: Automatic instance health monitoring

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines on:

• Development setup
• Code style and standards
• Testing requirements
• Pull request process

📚 Documentation

Accessing Documentation

ClaudeBench provides comprehensive documentation through multiple channels:

🌐 Docusaurus Documentation Site

# Start the documentation server
cd docs && bun dev
# Access at http://localhost:3002

🖥️ Integrated Documentation Viewer

The web application includes an embedded documentation viewer:

1. Start the main application: bun dev
2. Navigate to the Docs tab in the sidebar
3. Browse documentation within the ClaudeBench interface

📡 API Documentation Access

Programmatic access to documentation via handlers:

• docs.list - List all documentation with metadata
• docs.get - Retrieve specific document content

Documentation Structure

The documentation source files are located in docs/docs/ and organized as follows:

• Getting Started - Quick introduction and setup
• Architecture - System design and patterns
  • Event Bus & Redis integration
  • Handler patterns and decorators
  • MCP (Model Context Protocol) integration
  • Circuit breakers and resilience
• API Reference - Complete API documentation
  • Task operations
  • System management
  • Swarm intelligence
• Guides - Practical tutorials and examples
• Handlers - Handler implementation details

You can browse the documentation directly in the docs/docs/ directory or view them through the Docusaurus interface.

🛠️ Technology Stack

• Runtime: Bun - Fast JavaScript runtime
• Backend: Hono - Lightweight web framework
• Frontend: React + TanStack Router
• Database: PostgreSQL + Prisma
• Cache/Queue: Redis
• Styling: Tailwind CSS + shadcn/ui
• Testing: Bun Test + Vitest

📄 License

ClaudeBench is MIT licensed. See LICENSE for details.