Claude Bridge

Key-free AI classification by driving the local claude CLI — no API key required.

Classify feedback with AI without an API key by driving the local claude CLI (which bills against a Claude Max/Pro plan). Embedding + semantic dedup still run free, inline, on Workers AI in the cloud; only the LLM classification step (type / sentiment / urgency / priority / summary) is delegated to your machine.

This sidesteps the "overage credits ≠ API credits" wall — no OpenAI or Anthropic API key required.

How it works

Worker (cloud)                          Your machine (local)
──────────────                          ────────────────────
feedback_items.ai_type IS NULL   ◄───   GET  /api/v1/admin/ai/pending
                                         for each item:
                                           claude -p <prompt> --output-format json
                                           → {type, urgency, sentiment_score, …}
storeClassification + priority   ◄───   POST /api/v1/admin/ai/classify-result

GET /api/v1/admin/ai/pending?limit=N — items still needing classification (ai_type IS NULL). Header x-admin-token: <ADMIN_API_TOKEN>.
POST /api/v1/admin/ai/classify-result — body { feedbackId, type, product_area, urgency, confidence, sentiment_score, summary, urgency_keywords }. Stores it exactly like the inline pipeline and recomputes the priority score.
scripts/claude-bridge.py — the poller that ties them together.

Quick start

cd <repo>

# Classify everything currently pending, once, then exit:
CV_ONCE=1 ./scripts/claude-bridge.py

# Or run continuously — polls every 10s and classifies new feedback as it lands:
./scripts/claude-bridge.py

Each item is one claude -p call (a few seconds), billed to your Max/Pro plan.

Configuration (env vars)

Var	Default	Meaning
`CV_API_BASE`	`https://feedback-dev.jfcreations.com`	Worker base URL
`CV_ADMIN_TOKEN`	`cv-demo-admin-2026`	Sent as `x-admin-token`
`CV_POLL_SECONDS`	`10`	Poll interval (loop mode)
`CV_BATCH`	`10`	Items fetched per pass
`CV_CLAUDE_BIN`	`claude`	Path to the `claude` CLI
`CV_ONCE`	(unset)	If set, run one pass and exit

Troubleshooting

claude not found — the Python subprocess does not see shell aliases. If your claude is an alias (e.g. ~/.local/bin/claude), pass the real path:
```
CV_CLAUDE_BIN="$HOME/.local/bin/claude" CV_ONCE=1 ./scripts/claude-bridge.py
```
Nothing pending — everything is already classified. Submit feedback (or lower the bar) and re-run.
401 Unauthorized — CV_ADMIN_TOKEN doesn't match the worker's ADMIN_API_TOKEN.
Parse errors — claude returned non-JSON. The bridge logs and skips that item; it's retried on the next pass (the row stays ai_type IS NULL).

When to use which classifier

The pipeline picks an LLM in this order; the bridge is independent of all of them:

Bridge (this) — key-free, runs on demand from your machine. Recommended while you have a Max/Pro plan but no API budget.
OpenAI — set wrangler secret put OPENAI_API_KEY; classification then runs automatically on submit (inline).
Anthropic — set wrangler secret put CLAUDE_API_KEY; same, inline.

The bridge and the inline path coexist: embedding/dedup are always inline + free; the bridge fills in classification for anything an inline LLM didn't (or for all items, if no inline key is set).

Keeping the prompt in sync

scripts/claude-bridge.py embeds a copy of the classification prompt that mirrors src/lib/ai/llm.ts (CLASSIFICATION_PROMPT). If you change the schema or instructions there, update the bridge's PROMPT_TEMPLATE to match.