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.
- 🔴 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
┌─────────────────────────────────────────────────┐
│ 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) │
└───────────────────────────────────────────────┘
- Install Claudebench from this repo
- Go to your project folder and run
bun run {CLAUDEBENCH_FOLDER}/scripts/claudebench-init.tsto onboard your repository - Launch
claudeand sayhi, he should carry on and you should be good to use tasking system of claudebench
- Bun >= 1.2.0 (Install Bun)
- Redis >= 6.0 (Local or Docker)
- PostgreSQL >= 14 (Local or Docker)
- Node.js >= 18 (for some tooling)
# 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# Start PostgreSQL with Docker
bun db:start
# Run database migrations
bun db:push
# (Optional) Open Prisma Studio to view data
bun db:studio# 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 devThe event relay provides real-time monitoring of system events:
# Start the relay for monitoring
bun relayClaudeBench 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 checkTasks progress through these states:
pending- Awaiting assignmentin_progress- Currently being worked oncompleted- Successfully finishedfailed- Encountered an error
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
});// 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 }
});// 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"]
});# 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:watchClaudeBench 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
We welcome contributions! Please see CONTRIBUTING.md for guidelines on:
- Development setup
- Code style and standards
- Testing requirements
- Pull request process
ClaudeBench provides comprehensive documentation through multiple channels:
# Start the documentation server
cd docs && bun dev
# Access at http://localhost:3002The web application includes an embedded documentation viewer:
- Start the main application:
bun dev - Navigate to the Docs tab in the sidebar
- Browse documentation within the ClaudeBench interface
Programmatic access to documentation via handlers:
docs.list- List all documentation with metadatadocs.get- Retrieve specific document content
The documentation source files are located in docs/docs/ and organized as follows:
- Getting Started - Quick introduction and setup
- Architecture - System design and patterns
- API Reference - Complete API documentation
- 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.
- 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
ClaudeBench is MIT licensed. See LICENSE for details.