claudebench

ClaudeBench is a Redis-first, event-driven AI workbench designed to orchestrate Claude-based AI tasks with swarm-inspired decomposition. It exposes a real-time tasking system driven by a JSONRPC 2.0 protocol and emits live updates over WebSocket, enabling you to monitor task progress and metrics as tasks flow through Redis streams, a swarm intelligence layer, and a PostgreSQL persistence layer. You can onboard repositories, create and claim tasks, decompose complex objectives into subtasks, and track task histories with automatic commit-like context. The MCP integration makes ClaudeBench capable of integrating AI tools and agents as part of a broader tooling ecosystem, coordinating actions via standardized model-context interactions.

To use the server, install the repository dependencies, configure the environment, and launch the server. The included API documentation and examples illustrate how to call operations such as creating tasks, claiming them for workers, completing tasks with results, and managing swarm projects. Real-time monitoring is available through the built-in event relay and dashboards, letting you observe task creation, decomposition, and execution as they happen.

Prerequisites:

• Bun runtime installed (>= 1.2.0) or a compatible Node.js environment for serving, Redis 6.0+ and PostgreSQL 14+ available locally or in Docker
• Redis and PostgreSQL configured (local or dockerized)
• Git and standard CLI tools available

Installation steps:

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

2. Install dependencies (via Bun, as recommended by the project): bun install

3. Copy environment variable templates to actual config: cp .env.example .env cp apps/server/.env.example apps/server/.env cp apps/web/.env.example apps/web/.env

4. Update the .env files with your configuration (database credentials, Redis, etc.).

5. Start the database services and migrations (these scripts are provided by the project): bun db:start bun db:push bun db:studio # optional

6. Run the application (start both backend and frontend with bun dev): bun dev

Optional:

• Start documentation site if needed: cd docs && bun dev
• Start the event relay for monitoring: bun relay

Notes and tips:

• Ensure Redis and PostgreSQL are reachable from the environment where the server runs; consider using Docker for local testing.
• The project uses Bun for performance; ensure Bun is up-to-date to avoid compatibility issues with scripts like bun dev and bun relay.
• The MCP integration expects a model-context capable workflow; if you’re introducing external tools, verify that the context generation and tool invocation patterns align with your agents’ capabilities.
• If you encounter environment variable issues, double-check the copied .env files and ensure all required variables (e.g., database URLs, Redis connection details) are properly set.
• For debugging, use the event relay and real-time dashboard to trace task flow and swarm decomposition steps, which can help diagnose bottlenecks in task distribution or worker assignment.