# RepoCritics for AI Agents

> Review. Share. Archive. Every open-source repo.
> Pre-processed OSS knowledge — for developers and AI agents.

This document tells **AI coding agents** (Cursor, Cline, Claude Code, Devin, custom agents)
how to consume RepoCritics efficiently. Read the [llms.txt](./llms.txt) for the
machine-readable index. Save your LLM tokens.

## Why RepoCritics exists for agents

When you (an agent) need to evaluate an open-source dependency you typically:

1. Fetch the GitHub README (~2-4K tokens).
2. Skim recent issues / PRs (~5-15K tokens).
3. Check stars / activity (~1K tokens).

That is **10-20K tokens for a single dependency check**. RepoCritics pre-computes the
answer once and serves it back as a ~500-token JSON object.

## 4-layer identity

RepoCritics is four overlapping products:

1. **Metacritic for OSS** — qualitative critic + audience scores.
2. **Namuwiki for OSS** — community-maintained markdown wiki with history.
3. **SteamDB for OSS** — browser extension overlay on GitHub / GitLab.
4. **LLM token saver** — distilled, agent-readable JSON for AI consumers.

## URL scheme

Every repository has a stable URL of the form:

```
/repos/{platform}/{owner}/{name}
```

Examples:

- `/repos/github/facebook/react`
- `/repos/gitlab/gitlab-org/gitlab`
- `/repos/gitee/{owner}/{name}`
- `/repos/sourceforge/_/{name}` (no owner → `_`)
- `/repos/svn/{host}/{path-encoded}`

Old `/repos/{owner}/{name}` URLs 307-redirect to `/repos/github/{owner}/{name}`.

## Agent endpoints (Phase 2.5)

These ship **after the MVP**. Until then, scrape the HTML page — every repo page
includes Schema.org JSON-LD, so the data is structured.

```
GET /api/v1/repos/{platform}/{owner}/{name}
GET /api/v1/repos/{platform}/{owner}/{name}/wiki
GET /api/v1/repos/{platform}/{owner}/{name}/reviews
GET /api/v1/search?q=...&limit=10
GET /api/v1/popular?platform=github&limit=20
```

### Authentication

```
Authorization: Bearer rk_<your-api-key>
```

Anonymous requests are allowed but rate-limited to 100/day per IP.

### Sample response (Phase 2.5 preview)

```json
{
  "platform": "github",
  "owner": "facebook",
  "name": "react",
  "canonical_url": "https://github.com/facebook/react",
  "critics_score": 87,
  "audience_score": 92,
  "final_score": 89,
  "summary": "Mature UI library. Server Components ergonomic but debugging streaming errors still rough.",
  "key_risks": ["RSC streaming error UX", "Concurrent mode adoption cost"],
  "last_updated": "2026-05-23T10:00:00Z"
}
```

## Best practices for agents

- **Cache aggressively.** Repo pages are ISR (24h). Wiki and reviews can be cached
  for at least 1 hour.
- **Respect rate limits.** Use `Retry-After` on 429.
- **Honor robots.txt.** We allow crawl of public pages and disallow
  `/admin`, `/dashboard`, `/api/v1/auth/*`.
- **Cite the canonical URL** when summarizing for a human user.

## Submitting missing repos

Agents may POST to `/api/claim` (Phase 1 stub today, Phase 1H real backend):

```json
POST /api/claim
{ "url": "https://github.com/foo/bar" }

→ 202 { "status": "pending", "queue_position": 1, "estimated_wait_min": 5 }
```

SSRF / private-IP / non-VCS URLs are rejected with HTTP 400/403.

## Contact

Open an issue at [github.com/repocritics/repocritics](https://github.com/repocritics/repocritics)
or read the [public roadmap](https://repocritics.com/about).