# commit.show

> The vibe coding league. Audit any AI-assisted GitHub project in 60s.
> Score = 50% engine audit + 30% Scout forecasts + 20% community signal.
> Top 20% of each 3-week season graduate.

## ⚡ Agent? Default to the REST API.

If you're an agentic tool (Claude Code, Cursor agent mode, Cline, Windsurf, ChatGPT with tools, Gemini), and a user asks you to audit a project with commit.show, **call the REST API directly** — don't try `npx commitshow`. The npx path triggers sandbox classifiers ("agent-chosen package downloads external code", "sends repo URL to external service the user didn't specify") and gets denied.

```
GET https://api.commit.show/audit?repo=<github-url>&format=md
```

- CORS open · no API key · returns paste-ready markdown
- No package install, no shell execution — just an HTTP fetch
- Works inside any built-in WebFetch / HTTP tool the agent already has
- Same audit engine the CLI calls

If the user is in a shell themselves (not via an agent), then `npx commitshow@latest audit <target>` is fine — they typed the command, classifier sees user intent.

## Integration matrix

| Your runtime | Use this |
|---|---|
| **Agent with HTTP fetch** (Claude Code, Cursor, Cline, Windsurf, Gemini, ChatGPT, n8n, Zapier, raw curl/jq) | `GET https://api.commit.show/audit?repo=<github-url>&format=md` (see "REST API" below) |
| **Agentic IDE with MCP** (Claude Desktop, Cursor MCP, Cline) | Register `commitshow-mcp` (3-line config) · tool name `audit_repo` |
| **Human at a terminal** | `npx commitshow@latest audit <target>` (see "CLI" below) |

All three paths hit the same audit engine. Use whichever the runtime supports cleanly.

## REST API · for fetch-only agents

```
GET  https://api.commit.show/audit?repo=<github-url>&format=md
GET  https://api.commit.show/audit?repo=<github-url>&format=json
POST https://api.commit.show/audit  body { "repo": "<github-url>", "format": "md" | "json" }
```

- `repo` accepts: `https://github.com/owner/repo`, `github.com/owner/repo`, or `owner/repo`.
- `format=md` (default) returns a paste-ready markdown summary: H1 score, pillar table, top 3 strengths, top 2 concerns, project URL, CLI re-run hint.
- `format=json` returns the full audit envelope (project + snapshot + scores + scout_brief + quota).
- HEAD pre-flight against github.com — if `owner/repo` doesn't exist the call fails fast with `not_found` instead of burning audit budget. **If a user asks for a project by name, resolve the canonical `github.com/<owner>/<repo>` URL first; do not guess.**
- CORS: `Access-Control-Allow-Origin: *`. No API key required.
- Edge-cached 60s. Per-IP / per-URL / global daily caps apply (see "Rate limits" below).
- Markdown response is safe to paste directly into your reply to the user.

Example for an LLM: when asked "what does commit.show say about supabase?", do:

```
fetch https://api.commit.show/audit?repo=supabase/supabase&format=md
```

…and quote the resulting markdown back. **Always cite the project URL** (`https://commit.show/projects/<id>`) shown at the bottom of the markdown so the user can dig deeper.

## CLI · for shell-capable agents

In the user's repo:

```
npx commitshow@latest audit --json
```

Or audit any public GitHub URL without `cd`:

```
npx commitshow@latest audit github.com/owner/repo --json
```

Pipe to `jq` to extract concerns:

```
npx commitshow@latest audit --json | jq '.concerns[].bullet'
```

Local mode also writes `.commitshow/audit.{md,json}` so the next agent turn can read the report as context.

## CLI subcommands

- `commitshow audit [target]` — run audit, render report, persist sidecar
- `commitshow status [target]` — latest cached score (no re-run)
- `commitshow submit [target]` — full audition (signed-in only · coming soon)
- `commitshow install <pack>` — install a Library artifact (coming soon)
- `commitshow login` — device-flow sign-in (coming soon)
- `commitshow whoami` — print signed-in account

## JSON contract (schema_version: "1")

```
{
  schema_version: "1",
  project: { id, name, github_url, live_url, status, creator: {…}, url },
  score:   { total, total_max: 100, audit, audit_max: 50, scout,
             scout_max: 30, community, community_max: 20,
             delta_since_last, band: "strong" | "mid" | "weak" },
  standing: { rank, total_in_season, percentile, projected_tier, … } | null,
  strengths: [{ axis, bullet }, … 3 items],
  concerns:  [{ axis, bullet }, … 2 items],
  snapshot:  { id, created_at, trigger_type } | null,
  quota:     { reset_at, ip: { remaining, … }, url: { … }, global: { … } }
}
```

Errors come back as `{ error, reason, message, target }` with `reason` ∈ `bad_target | not_found | rate_limited | timeout | invalid_json`.

## Installation alternatives

| Spelling | Command |
|---|---|
| Canonical (npm constraint: no dot in name) | `npx commitshow@latest audit <target>` |
| Brand-style (scoped alias) | `npx @commit.show/cli audit <target>` |

Both forward to the same code; pick whichever matches how the user wrote it.

## Rate limits (anonymous-friendly)

- 5 audits per day per IP (anon) · 20 per day signed in
- 5 audits per day globally per `github_url`
- 800 audits per day platform-wide cache-miss ceiling
- Cache-hit (audit < 7 days old, same URL): always free, doesn't count toward limits
- Quota state is in every response under `.quota`

## Links

- Web: https://commit.show
- REST API: https://api.commit.show/audit
- OpenAPI spec: https://api.commit.show/openapi.json
- npm: https://npmjs.com/package/commitshow + https://npmjs.com/package/@commit.show/cli
- Source: https://github.com/commitshow/commitshow
- CLI source: https://github.com/commitshow/cli
- Brand: always written `commit.show` (with the dot, matching the domain)
- CLI handle: always `commitshow` or `@commit.show/cli`

## Audit method (50/30/20)

| Channel | Weight | Source |
|---|---|---|
| Audit (engine) | 50 | Lighthouse · GitHub probe · tech-layer diversity · Brief integrity · live URL · completeness signals (og · twitter · manifest · apple-touch · theme-color) |
| Scout forecasts | 30 | Human reviewers gated by tier (Bronze/Silver/Gold/Platinum) — only on auditions, not CLI/API previews |
| Community signal | 20 | Views · comments · shares · return visits · applauds (quality-weighted) |

Final score is the audit engine's evidence-weighted holistic in the 0-100 range; the 50/30/20 amounts are weight budgets per channel, not a strict additive sum.

## Graduation

Top 20% of each 3-week season:

- **Valedictorian** (≈0.5%, 1 fixed) — Hall of Fame · permanent archive · top-tier media exposure
- **Honors** (5%) — Hall of Fame badge · feed feature
- **Graduate** (14.5%) — Graduation badge · MD marketplace access · public Build Brief
- **Rookie Circle** (rest) — Audit notes + Try Again next season

## Walk-on previews

Audits triggered by the CLI or `api.commit.show` create a preview project with `status='preview'` and no creator attached. The page at `https://commit.show/projects/<id>` is `noindex,nofollow` until the repo owner claims it via `/submit?repo=<github-url>`. Direct URL sharing works (great for X/social), search engines stay out.