leetclawd

Leetclawd is a Next.js app that generates coding problems with the Claude Code CLI, streams progress to the browser, verifies tests against an auto-generated solution, and saves problems to a local SQLite database for practice.

Architecture overview

flowchart TD
  UI[Browser UI] -->|POST /api/generate/stream| Gen[Generate route]
  Gen -->|spawn CLI| CLI[Claude Code CLI]
  CLI -->|stream-json NDJSON| Gen
  Gen -->|SSE events| UI
  Gen -->|insert| DB[(SQLite)]

  UI -->|POST /api/submit| Submit[Submit route]
  Submit -->|run tests| Runner[lib/test-runner]
  Runner -->|results| Submit
  Submit -->|JSON| UI

  UI -->|POST /api/chat| Chat[Chat route]
  Chat -->|stream| CLI
  Chat -->|SSE| UI

Problem generation pipeline

sequenceDiagram
  participant U as User
  participant UI as App UI
  participant API as /api/generate/stream
  participant C as Claude CLI
  participant T as Test Runner
  participant DB as SQLite

  U->>UI: Start generation
  UI->>API: POST (stream)
  API->>C: Spec -> tests -> audit -> solution
  API->>T: Run tests
  API-->>UI: SSE status + delta
  alt Tests pass
    API->>DB: Save problem + logs (status: success)
    API-->>UI: complete
  else Tests fail
    API->>DB: Save problem + logs (status: failed)
    API-->>UI: error
  end

Features

• Problem Generation: Claude generates problem specs, test cases, audits them, and writes a verified solution
• Solution Fix Reasoning: When solutions fail tests, Claude analyzes failures before retrying
• Chat Interface: Ask Claude questions about the current problem for hints and guidance
• Generation Status: Track whether problems were generated successfully or failed verification
• Submission History: View past successful submissions with syntax highlighting

Getting started

1. Install dependencies: npm install
2. Run the dev server: npm run dev
3. Open http://localhost:3000

Requirements

• Claude Code CLI: Must be installed and authenticated. The app spawns the CLI directly.
• Node.js: Required for the test runner (JS/TS solutions run in vm sandbox)
• Python (optional): For Python problem support
• Java (optional): For Java problem support (uses bundled Gson jar)

Security notes

• Claude Code CLI can run tools (bash/edit/read) depending on CLI config
• Do not expose the generation or chat endpoints publicly without restricting tool access

Documentation

• Architecture and verification flow: docs/app-architecture.md
• Claude Code streaming pattern: docs/claude-code-streaming.md

Repo layout

app/
  api/
    generate/stream/  # Problem generation with SSE
    chat/             # Chat with Claude about problems
    submit/           # Run user solutions against tests
    problems/         # List/delete problems
  problem/            # Problem practice UI
components/           # React components
lib/
  db/                 # SQLite schema and queries
  claude.ts           # Claude CLI bridge
  test-runner.ts      # Solution test execution
  languages.ts        # Language-specific helpers
data/                 # SQLite database (gitignored)
problems/             # Starter code files (gitignored)
public/               # Static assets (3D models, etc.)
docs/                 # Architecture documentation