Claudeflare (Advisory-first)

Self-calibrating code quality scoring with reliability-weighted consensus + semantic signal precedent (Vectorize).

┌────────────────────────────────────────────────────────────────┐
│  Claude scores code → Developers give feedback → System learns │
│                                                                │
│  Non-blocking: advisory guidance, never a hard gate            │
└────────────────────────────────────────────────────────────────┘

What it does now

• Reliability-weighted consensus learning: Aggregates developer feedback with per-dimension reliability weighting
• Personal Biases (EMA): Track individual preferences per user with exponential moving average
• Natural Language Reasons: Attach context to calibration signals
• Vectorize Integration: Semantic search for similar calibration signals (precedent)
• Signal Types: Explicit (manual), Inferred (from comments), Auto (CI-generated)
• Six Dimensions: code_quality, test_coverage, security, performance, ui_design, documentation
• SSE Control Tower: Stream plan/dispatch/scoring/learning events live by job_id

What each install option provides

| Option | Status | You get | Best for | |---|---:|---|---| | Hosted Worker (this repo deployed) | Now | REST API + D1/KV/Vectorize state, scoring, learning, SSE job event stream | The “service” everything talks to | | GitHub App | Roadmap | One-click org/repo install, PR-native UX (checks/comments), centralized auth + allowlisting | Product-grade default install for teams | | npx … init (per repo) | Now | Creates .claudeflare.json (safe to commit) so tools/CI have stable project_id + Worker URL | Fast per-repo onboarding without secrets | | npx … mcp install (per machine, optional) | Now | Registers a local MCP server entry so Claudeflare tools show up inside Claude Desktop/Code | “Feel it during coding” (commands + receipts) | | Local MCP proxy (npx … mcp serve) | Now | A stdio MCP server that forwards tool calls to the Worker’s REST endpoints (uses env/config for URL/token) | Bridges Claude MCP ⇄ Worker REST securely |

Product roadmap (recommended packaging)

• Phase 1: GitHub App + hosted service (Worker) + docs

  • One-click install per org/repo
  • Posts advisory PR summaries + links to SSE traces
  • Centralized auth + project allowlisting (no shared secrets copied to every repo)

• Phase 2: npx CLI for local + optional MCP proxy

  • Per-repo bootstrap: npx … init writes .claudeflare.json (no secrets)
  • Optional “Claude plugin”: npx … mcp install registers a local stdio MCP proxy
  • Keeps CI + automations on REST/SSE, while giving developers first-class in-Claude tools

Quick Start

# Clone and deploy
git clone https://github.com/ThinAirTelematics/claudeflare
cd claudeflare
pnpm install
pnpm db:migrate
pnpm deploy

Your MCP server is now live at https://claudeflare.thinair.workers.dev

One-line installer for developers (per project)

From any repo you want to use Claudeflare on:

npx claudeflare-mcp init

This writes a .claudeflare.json in the repo (safe to commit; no secrets). It will infer owner/repo from git remote origin when possible.\n+ Provide your token via env (recommended) or CI secrets:\n+

• CLAUDEFLARE_TOKEN (sent as X-API-Token)\n+

One-line Claude MCP plugin (optional)

If you want Claudeflare tools available directly inside Claude via MCP, install the local MCP proxy:

npx claudeflare-mcp mcp install

This registers mcpServers.claudeflare pointing at a local stdio proxy that forwards tool calls to your deployed Worker.\n+ To use protected tools (compute_score, calibration_submit), provide a token to Claude either by editing the config or setting CLAUDEFLARE_TOKEN.

Architecture

┌─────────────┐     ┌─────────────────┐     ┌──────────────┐
│   Claude    │────▶│  MCP Server     │────▶│  D1 + KV     │
│  (scoring)  │◀────│  (data layer)   │◀────│  (storage)   │
└─────────────┘     └─────────────────┘     └──────────────┘
       │                    │                      │
       │                    ▼                      ▼
       │            ┌─────────────────┐    ┌─────────────┐
       └───────────▶│ Dawid-Skene     │    │  Vectorize  │
                    │ Calibration     │    │  (semantic) │
                    └─────────────────┘    └─────────────┘

MCP Tools

| Tool | Purpose | |------|---------| | get_profile | Fetch calibration state (biases, confidence, reliability) | | record_signal | Log developer feedback on a dimension | | compute_score | Calculate calibrated scores → advisory PASS/WARN/BLOCK + explain + precedent | | get_patterns | Retrieve CLAUDE.md patterns for context | | parse_signals | Extract feedback signals from PR comments | | calibration_submit | Batch submit signals with reasons (embeds to Vectorize) | | query_similar_signals | Semantic search for related calibration signals | | get_signal_context | Get recent + similar signals for a dimension |

Calibration Submit (New in V2.2)

POST /tool/calibration_submit
{
  "project_id": "owner/repo",
  "user_id": "barrett",
  "signals": [
    {
      "dimension": "code_quality",
      "delta": 5,
      "reason": "Code follows established patterns well"
    },
    {
      "dimension": "security",
      "delta": -8,
      "reason": "Edge validation should be stricter"
    }
  ]
}

Response:

{
  "success": true,
  "signals_recorded": 2,
  "signals_embedded": 2,
  "personal_biases": {
    "biases": { "code_quality": 4.05, "security": -2.4, ... },
    "confidence": 0.15,
    "total_signals": 3
  }
}

Semantic Signal Search

POST /tool/query_similar_signals
{
  "project_id": "owner/repo",
  "query": "edge validation preferences",
  "dimension": "security",
  "limit": 10
}

Returns semantically similar calibration signals for context.

API Endpoints

| Endpoint | Method | Description | |----------|--------|-------------| | /health | GET | Health check | | /tools | GET | MCP tool manifest | | /tool/{name} | POST | Execute MCP tool | | /profile/{project_id} | GET | Quick profile fetch | | /api/score | POST | Compute calibrated score (protected) | | /api/signal | POST | Record signals (protected) | | /api/job/{job_id}/events | GET | SSE stream of job events (protected) | | /sse | GET/POST | SSE transport for MCP |

Scoring Dimensions

| Dimension | Weight | Target | |-----------|--------|--------| | code_quality | 30% | 85 | | security | 25% | 90 | | test_coverage | 15% | 80 | | ui_design | 15% | 85 | | performance | 10% | 80 | | documentation | 5% | 75 |

Calibration Flow

1. Claude scores code (raw scores)
2. System applies biases: calibrated = raw + bias
3. Compute verdict: PASS (≥target) / WARN (≥target-10) / BLOCK
4. Developer provides feedback with natural language reason
5. Signal embedded to Vectorize for semantic retrieval
6. Personal biases updated with EMA (α=0.3)
7. Project biases recalculated via reliability-weighted consensus
8. Vectorize retrieval adds precedent (soft confidence modifiers + explainability)

Project Structure

claudeflare/
├── src/
│   ├── index.ts      # MCP server (Hono + Workers)
│   ├── tools.ts      # MCP tool handlers + Vectorize
│   └── learning.ts   # reliability-weighted consensus + structured signals
├── migrations/
│   └── 001_schema.sql
├── wrangler.toml
└── package.json

Development

pnpm dev          # Local dev server (port 8787)
pnpm typecheck    # Type check
pnpm deploy       # Deploy to Cloudflare

Stack

• Runtime: Cloudflare Workers + Hono
• Database: Cloudflare D1 (SQLite)
• Cache: Cloudflare KV
• Embeddings: Cloudflare Workers AI (bge-base-en-v1.5)
• Semantic Search: Cloudflare Vectorize

Feeling the power in Claude Code (commands + SSE)

• Commands: /plan, /score, /learn, /profile, /watch <job_id>
• Receipts: every command returns stable IDs (job_id, score_run_id, signal_id) so you can fetch artifacts later.
• Live stream: connect to GET /api/job/{job_id}/events to watch routing, workstream claims, artifact submits, retrieval, and scoring in real time.

Item identity (prevents phantom bias)

When available, include these fields so learning attaches to a concrete review event:

• pr_number, commit_sha, diff_hash (optional but ideal), artifact (frontend/backend/docs/infra/mixed)
• item_id (optional) can be provided; otherwise Claudeflare derives one from PR/SHA/diff_hash.
• No Pages: Workers handle everything

Cost: $0*

| Component | Cost | |-----------|------| | Cloudflare Workers | Free (100k req/day) | | Cloudflare D1 | Free (5GB) | | Cloudflare KV | Free (100k reads/day) | | Cloudflare Vectorize | Free (5M vectors) | | Workers AI | Free (10k neurons/day) | | Claude analysis | Your subscription |

*Free tiers cover most use cases.

Self-calibrating quality that learns from your team.