claudebench: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

ClaudeBench is a Redis-first event-driven system where every handler auto-generates HTTP, MCP, and event interfaces through a single decorator. The architecture enforces localhost-reality: no distributed complexity for single-user tools.

Critical Commands

bun relay               # MUST run in background - monitors all system events
bun dev                 # Start server (:3000) and web (:3001)
bun test:contract       # Test external API contracts (specs/001-claudebench/contracts/)
bun test:integration    # Test internal Redis/Prisma side effects

Codebase Architecture

Handler-Centric Design

Every feature is a handler in apps/server/src/handlers/{domain}/. The handler IS the feature:

// apps/server/src/handlers/task/task.create.handler.ts
@EventHandler({
  event: 'task.create',              // Becomes HTTP POST /task/create
  inputSchema: taskCreateInput,      // Shared schema from schemas/
  outputSchema: taskCreateOutput,    // Type-safe everywhere
  persist: true,                     // Handler decides PostgreSQL persistence
  rateLimit: 10
})
export class TaskCreateHandler {
  @Instrumented(0)                   // Caching TTL (0 = no cache)
  @Resilient({                       // Per-handler resilience config
    rateLimit: { limit: 100, windowMs: 60000 },
    timeout: 5000,
    circuitBreaker: { threshold: 5, timeout: 30000 }
  })
  async handle(input: TaskCreateInput, ctx: EventContext) {
    // 1. Atomic Redis operations via Lua scripts
    const result = await redisScripts.createTask(...);
    
    // 2. Conditional PostgreSQL persistence
    if (ctx.persist) {
      await ctx.prisma.task.create({ data });
    }
    
    // 3. Publish events for observers
    await ctx.publish({ type: 'task.created', payload });
    
    return output; // Validated by outputSchema
  }
}

Directory Structure Patterns