Auditing a Repository
Submit a public GitHub repo for an automated code-quality + data-hygiene audit. Signed-in users get 5/day; anonymous get 1/day.
Auditing a Repository
The /audit page accepts a public GitHub URL and runs an automated critique — kb-api ingests the repo, a Haiku model writes a short review, and the result is persisted at /audit/[id].
Running an audit
- Open
/audit - Paste a public GitHub URL (e.g.
https://github.com/owner/repo) - Check the publish-consent box — audits are public by default
- Submit
The UI runs a state machine: idle → submitting → inflight → complete / failed. It polls /api/demo/audit/{id} every 2 seconds with an AbortController that cleans up on unmount.
A typical audit takes 1–3 minutes. Stages in order:
| Stage | What happens |
|---|---|
queued | Row inserted, waiting for the background worker |
ingesting | kb-api clones the repo and extracts files |
indexing | Embeddings generated, stored, neighbors computed |
critiquing | Anthropic Haiku writes the Markdown review |
complete | Result available at /audit/[id] |
Quota
| Caller | Daily limit |
|---|---|
| Anonymous (by hashed IP) | 1 audit / day |
| Signed in (Clerk) | 5 audits / day |
Failed audits don't count against quota — if a job errors out, you can retry freely. A global concurrency cap of 3 in-flight audits across all users prevents runaway load; when hit, the API returns 503 with Retry-After: 60.
Deduplication
If you submit the same repo URL twice within 24 hours and already have a complete audit for it, the API returns the existing audit_id instead of starting a new job. The response includes "deduped": true so the UI can skip straight to the result view.
Result shape
A completed audit includes:
- Markdown critique — a code/data quality review authored by Claude Haiku
- Entity ID — the repo joins the knowledge graph as a linkable entity
- Neighbors — 8 k-NN similar repos from the kb-api index
- Stored view —
/audit/[id]is a permalink anyone can revisit
History (signed-in only)
Signed-in users can view their past audits at /audit/history:
- Up to 200 most recent audits, newest first
- Delete button removes both the audit row and the corresponding entity from kb-api
Reconciliation
Audits that get stuck (Railway redeploy drops the BackgroundTask, kb-api times out, etc.) are caught by a periodic reconciler that runs every 60 seconds and marks orphaned jobs as failed. Detection uses both updated_at > 10min and created_at > 15min thresholds so short-lived stalls don't false-positive.
Related
- API: Audit — endpoint reference
- Knowledge — where completed audits land in the graph