{"id":50395070,"url":"https://github.com/hsnice16/agent-friendly-code","last_synced_at":"2026-05-30T20:30:37.683Z","repository":{"id":353295692,"uuid":"1218249549","full_name":"hsnice16/agent-friendly-code","owner":"hsnice16","description":"A public dashboard that ranks open-source repos by how friendly they are for AI coding agents — per model.","archived":false,"fork":false,"pushed_at":"2026-05-21T09:47:04.000Z","size":3044,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-21T17:42:51.236Z","etag":null,"topics":["agent-friendly-code","ai","ai-code-rank","bun","dashboard","nextjs"],"latest_commit_sha":null,"homepage":"https://agentfriendlycode.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hsnice16.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":"hsnice16"}},"created_at":"2026-04-22T17:26:14.000Z","updated_at":"2026-05-21T09:47:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hsnice16/agent-friendly-code","commit_stats":null,"previous_names":["hsnice16/agent-friendly-code"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/hsnice16/agent-friendly-code","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hsnice16%2Fagent-friendly-code","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hsnice16%2Fagent-friendly-code/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hsnice16%2Fagent-friendly-code/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hsnice16%2Fagent-friendly-code/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hsnice16","download_url":"https://codeload.github.com/hsnice16/agent-friendly-code/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hsnice16%2Fagent-friendly-code/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33709269,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-friendly-code","ai","ai-code-rank","bun","dashboard","nextjs"],"created_at":"2026-05-30T20:30:35.920Z","updated_at":"2026-05-30T20:30:37.674Z","avatar_url":"https://github.com/hsnice16.png","language":"TypeScript","funding_links":["https://github.com/sponsors/hsnice16"],"categories":[],"sub_categories":[],"readme":"# Agent Friendly Code\n\n[![Release](https://img.shields.io/badge/release-0.6.0-blue?style=flat-square)](./lib/changelog.ts)\n[![License: MIT](https://img.shields.io/badge/license-MIT-green?style=flat-square)](./LICENSE)\n[![Next.js 16](https://img.shields.io/badge/Next.js-16-black?style=flat-square)](https://nextjs.org)\n[![Node ≥20.9](https://img.shields.io/badge/node-%E2%89%A520.9-43853d?style=flat-square\u0026logo=node.js\u0026logoColor=white)](https://nodejs.org)\n[![Sponsor](https://img.shields.io/badge/sponsor-%E2%9D%A4-db61a2?style=flat-square\u0026logo=githubsponsors\u0026logoColor=white)](https://github.com/sponsors/hsnice16)\n[![Agent Friendly](https://www.agentfriendlycode.com/api/badge/github/hsnice16/agent-friendly-code.svg)](https://www.agentfriendlycode.com)\n\n**A public dashboard that ranks open-source repos by how friendly they are for AI coding agents — per model.**\n\nNext.js 16 + SQLite (`better-sqlite3`), styled with Tailwind CSS 4. Spans GitHub, GitLab, and Bitbucket out of the box. Current release: **0.6.0**.\n\n![Agent Friendly Code — leaderboard](./public/demo/light.png)\n\n\u003cdetails\u003e\n\u003csummary\u003eDark mode\u003c/summary\u003e\n\n![Agent Friendly Code — leaderboard (dark theme)](./public/demo/dark.png)\n\nFollows `prefers-color-scheme` automatically — same tokens, different values.\n\n\u003c/details\u003e\n\n---\n\n## The idea\n\nAI coding agents — Claude Code, Cursor, Devin, GPT-5 Codex, Gemini CLI, Aider, OpenHands, Pi — succeed dramatically more often on some repos than others. The difference is rarely the agent; it's the repo. A codebase with fast tests, a clear `AGENTS.md`, a Makefile, and CI is a massively different environment than one without.\n\n**Goal**: a public leaderboard where anyone can look up a repo and see:\n\n1. How agent-friendly is it overall?\n2. How friendly is it for _my_ agent? (Claude Code weights `AGENTS.md` heavily; Devin cares about CI + reproducible envs; Cursor prefers strong types + a good README.)\n3. _Why_ does it rank there, and **what would it take to improve for my agent?** — top-3 gaps ranked by score-gain.\n\nTwo audiences:\n\n- **Maintainers** — a ranked checklist of what to fix to make their repo friendlier to agents.\n- **Agent users** — when picking between forks, packages, or alternatives, agent-friendliness is a real dependency-choice signal.\n\n## Prior art + what we do differently\n\n| Project                                                                   | What it does                                                                                                      | What we do differently                                                                                                                                                                            |\n| ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Factory.ai Agent Readiness**                                            | Single-tenant scanner: you point it at your repo and get a score with auto-fix PRs. 8 pillars, 5 maturity levels. | **Public + cross-forge + per-model.** Factory rates your own repo in isolation — we rank _across_ repos, on GitHub/GitLab/Bitbucket, and the ranking changes based on which agent you care about. |\n| **`kodustech/agent-readiness`**                                           | OSS alternative to Factory — static checks, local scan.                                                           | We're a public ranking service, not a local scanner. Scoring logic is similar in spirit; the product is the leaderboard and the per-model lens.                                                   |\n| **`jpequegn/agent-readiness-score`**                                      | Explicitly \"inspired by Factory.ai\" — OSS framework to measure codebase readiness.                                | Same delta as above — single-tenant vs. public + per-model.                                                                                                                                       |\n| **`viktor-silakov/ai-ready`**                                             | 39 checks, 7 pillars, 10+ languages. Scanner.                                                                     | Same delta.                                                                                                                                                                                       |\n| **`ambient-code/agentready`**                                             | Assesses git repos against evidence-based attributes.                                                             | Same delta.                                                                                                                                                                                       |\n| **Cloudflare Agent Readiness**                                            | Rates _websites_ for agent consumption.                                                                           | Wrong object — we rate code repos.                                                                                                                                                                |\n| **Fern Agent Score**                                                      | Public leaderboard rating _documentation_ sites for AI-readiness.                                                 | Closest in shape — public + leaderboard — but scores docs, not code.                                                                                                                              |\n| **Clarvia**                                                               | Scoring platform for _MCP servers_ (Agent Experience Optimization).                                               | Adjacent — rates tools, not repos.                                                                                                                                                                |\n| **SWE-Bench (Verified / Pro), GitTaskBench, FeatureBench, HAL, PR Arena** | Rank _agents_ on a fixed set of repos.                                                                            | We want the **transpose**: rank repos _per agent_. Our measurement story (once the benchmark harness lands) looks a lot like these, with the axes flipped.                                        |\n| **GitHub Trending, ossinsight**                                           | Popularity / activity rankings.                                                                                   | Stars ≠ agent-friendliness.                                                                                                                                                                       |\n\n**Our differentiators, in one line**: cross-forge, public, **per-model**, and explainable — every score decomposes to signals, and every repo page shows _what to improve next_ for the selected model.\n\n## Honest product concerns\n\nNot pretending the idea is free of risk:\n\n- **Per-model scoring is the hardest part and the easiest to fake.** Per-model rationales are now sourced from each agent's published docs (see `MODELS[].sources` in `lib/scoring/weights.ts`), but the weight values themselves are still pre-benchmark. Real \"Claude ranks this higher than GPT-5\" requires actually running each agent on each repo. That's `tasks/1.0.0/03-benchmark-harness.md`.\n- **Factory.ai is already in this space.** Differentiation has to stay sharp.\n- **Public-shaming risk.** Ranking #47,823 without consent invites angry maintainers. Planned via `tasks/0.7.0/01-opt-out-claim-flow.md`.\n- **Score gaming.** Once public, people add boilerplate `AGENTS.md` to pass the rubric without being useful. Dynamic (actually-run-an-agent) checks are the counter — see benchmark harness.\n- **Freshness.** Scores decay with every push. A 6-hourly GitHub Actions cron rescores the curated set; webhook-driven sub-minute refresh is deferred until the claim flow lands in 0.7.0.\n\nSee `/methodology` in the running app for a candid walkthrough of what's measured today and what isn't.\n\n## Security posture (FAQ)\n\nShort answer: **low risk**. The app:\n\n- Only **reads** files after a shallow clone; never executes anything from the cloned tree (no `npm install`, no post-clone hooks).\n- Uses `--depth 1 --single-branch` and never clones submodules.\n- Runs all SQL via prepared statements.\n- Renders through React (auto-escaping); the only `dangerouslySetInnerHTML` use is server-built JSON-LD with `\u003c` escaped to `\u003c`.\n- Has no auth and no writable API endpoints — read-only dashboard.\n\n**Operational concerns** for a public launch (not code-level security):\n\n- Disk quotas for the clone workspace.\n- Rate limiting the public API.\n- Sandbox the cloner in a container (future-proofing against hypothetical git CVEs).\n\nAuth and per-maintainer controls land with the opt-out / claim flow in v0.7.0.\n\n## Quickstart\n\n```bash\nbun install\nbun run prepare-hooks  # once — installs lefthook pre-commit (Biome + tsc + test + file-length)\nbun run seed           # score the curated set across GH / GL / BB + cache popular package aliases\nbun run dev            # http://localhost:3000\n```\n\nScore a single repo:\n\n```bash\nbun run score https://github.com/vercel/next.js\nbun run score https://gitlab.com/gitlab-org/cli\nbun run score https://bitbucket.org/snakeyaml/snakeyaml\nbun run score /path/to/local/checkout\n```\n\nOptional: `GITHUB_TOKEN` / `GITLAB_TOKEN` in env to raise API rate limits.\n\nRun the unit tests with `bun run test` (uses `node --test` + `tsx`; requires Node ≥20.9.0).\n\n## Versioning\n\n`lib/version.ts` and `package.json` carry the current release number (currently **0.6.0**). Bumps happen only when we actually cut a release — never when merging intermediate work. The version pill in the header surfaces the number directly; `/changelog` lists what each release shipped.\n\n## Stack \u0026 rationale\n\n| Choice                                               | Why                                                                                                                                          | When we'd revisit                                                                                  |\n| ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |\n| **Next.js 16 (App Router)**                          | Future features (filters, charts, auth, diff views) are React's territory. File-based routing + API routes replace hand-rolled HTTP cleanly. | Unlikely. The core scorer is stack-agnostic, only `app/` depends on this.                          |\n| **Node runtime (with `tsx` for CLI scripts)**        | Matches Vercel's serverless runtime — no Bun-only imports in prod. Bun still works locally as a fast package manager.                        | Unlikely — only if the deployment target changes.                                                  |\n| **Tailwind CSS 4**                                   | Zero-config via `@theme` tokens, no `tailwind.config.*` needed. Tight bundle output.                                                         | Would only leave for something with a stronger design-system story.                                |\n| **`better-sqlite3`**                                 | Single file, inspectable, zero ops overhead. Node-native so Vercel's serverless runtime can load it directly.                                | Postgres when concurrent writers / access control arrive (`tasks/1.0.0/01-postgres-migration.md`). |\n| **Server-first; client islands where needed**        | Cheap, fast, SEO-friendly. Client components only where interactivity demands — mobile nav, search, selects, copy, back-to-top.              | When client islands grow past presentational interactivity → reach for client state mgmt.          |\n| **Shallow git clones** (`--depth 1 --single-branch`) | Bandwidth + speed. Current signals don't need history.                                                                                       | If commit-history ever enters scoring → host APIs or `--filter=blob:none` partial clones.          |\n| **Exact-pinned deps**                                | Deterministic scoring across environments.                                                                                                   | Never.                                                                                             |\n| **One file per signal**                              | Each signal is a small, independent concern — keeps `git log` and code review focused.                                                       | When we bundle signals into dynamic checks (then the unit becomes the bundle).                     |\n\n## Why do we clone at all (instead of host APIs)?\n\n- Static signals need to read **file contents** (AGENTS.md length, `pyproject.toml [tool.X]` sections, package.json scripts count) — not just existence.\n- One clone is faster than N API calls for content-heavy scoring, and respects rate limits.\n- Any real version of this dashboard needs dynamic signals (run tests, run an agent). Those absolutely need code on disk.\n\n## Layout\n\n```text\napp/          Next.js App Router — pages + API + SEO\n  layout.tsx       root layout, root metadata (OG + Twitter cards)\n  page.tsx         leaderboard\n  repo/[id]/       repo detail (generateMetadata + per-repo OG image)\n  methodology/     how scoring works today\n  roadmap/         upcoming versions (from lib/roadmap.ts)\n  changelog/       what's shipped (from lib/changelog.ts)\n  about/           independent project, no vendor affiliation (footer-linked, E-E-A-T)\n  privacy/         privacy policy (footer-linked, AdSense/GDPR/CCPA)\n  terms/           terms of use (footer-linked)\n  action/          PR-diff GitHub Action explainer + install snippet\n  skill/           agent-skill explainer + install command\n  package/         registry → repo lookup (form + per-package state pages)\n  api/             /repos, /repo/[id], /score, /badge/\u003chost\u003e/\u003cowner\u003e/\u003cname\u003e, /package/\u003cregistry\u003e/\u003cname\u003e\n  robots.ts        /robots.txt — allows \"/\", blocks \"/api/\"\n  sitemap.ts       /sitemap.xml — static routes + every repo\n  llms.txt/        markdown manifest for LLM crawlers\n  globals.css      Tailwind import + @theme tokens\ncomponents/   React components (Tailwind-styled)\nlib/\n  scoring/    signals, weights, scorer — pure, no I/O outside the cloned tree\n  clients/    git clone, host API, npm/PyPI/Cargo registries\n  constants/  thresholds, host labels, sort keys\n  utils/      format + score-tier helpers, SVG badge renderer, package-request URL builder\n  db.ts       better-sqlite3 schema + queries (all SQL lives here)\n  package-lookup.ts  shared registry → repo lookup (used by /api/package + /package page)\n  version.ts  app + sibling URLs, install snippets (ACTION_USES, SKILL_INSTALL_CMD), SIBLING_VERSION pin\n  changelog.ts / roadmap.ts / skill-content.ts\nscripts/      CLI entries run via `tsx` (Node) — score, seed, init-db\ntests/        `node --test` unit tests — scorer, signals, URL parser, formatters\ntasks/        Per-version task breakdown (agent-readable)\npublic/       Static assets — demo/ screenshots used by the README + OG image\n.claude/      settings.json, hooks/ (Stop guard), skills/\ndata/         rank.db (committed — shipped as a build artifact; rescoring runs locally)\nAGENTS.md     Agent instructions (source of truth)\nCONTRIBUTING.md  Human-contributor guide — PR workflow, review bar\nCLAUDE.md     Pointer → AGENTS.md\nLICENSE       MIT\n```\n\n## Companion: PR-diff GitHub Action\n\n[`hsnice16/agent-friendly-action`](https://github.com/hsnice16/agent-friendly-action) runs the same scorer inside your CI and posts a per-PR score-delta comment — _\"this PR drops your Claude Code score by 4.1 points because it removed CI config.\"_ Opt-in via an `AGENTS_BADGE_TOKEN` secret; falls through silently when unset. Each repo detail page on the dashboard ships a copy-paste workflow snippet under \"Catch score regressions on every PR\".\n\n## Companion: agent skill\n\n[`hsnice16/agent-friendly-skill`](https://github.com/hsnice16/agent-friendly-skill) is a portable agent skill installable in one command — `npx skills add hsnice16/agent-friendly-skill#v0` — that scores the user's current repo locally and recommends a model. Profiles the same 8 agents this dashboard does (Claude Code, Cursor, Devin, GPT-5 Codex, Gemini CLI, Aider, OpenHands, Pi); installs into any [`vercel-labs/skills`](https://github.com/vercel-labs/skills)-compatible host (Cline, Copilot, Continue, Roo Code, …) and produces identical output regardless of which host invokes it — scoring is score-driven, not host-driven. Same self-contained property as the action: vendored scorer, no service dependency, works offline. The dashboard's [`/skill`](https://www.agentfriendlycode.com/skill) page hosts the install command, the score → model mapping, and optional `SessionStart` hook snippets for Claude Code and Codex.\n\n## Public API\n\nRead-only JSON endpoints for external integrators (skills, hooks, browser overlays, third-party tools):\n\n- `GET /api/score?host=\u003chost\u003e\u0026repo=\u003cowner\u003e/\u003cname\u003e` — look up an indexed repo by host + owner/name. Returns `{ repo, signals, modelScores }` on 200; `{ error: \"not_indexed\" }` with status 404 when the repo isn't in our DB. The natural lookup endpoint for any tool that has a repo URL but not our internal id.\n- `GET /api/repos` — full leaderboard (id, owner, name, host, stars, overall_score, per-model scores).\n- `GET /api/repo/\u003cid\u003e` — per-repo detail (signals, model scores, top improvements). Requires the internal id; use `/api/score` first if you only have host + owner/name.\n- `GET /api/badge/\u003chost\u003e/\u003cowner\u003e/\u003cname\u003e.svg` — embeddable SVG badge. `?model=\u003cid\u003e` for per-model variants.\n- `GET /api/package/\u003cregistry\u003e/\u003cname\u003e` — resolve npm / PyPI / Cargo package → source-repo score (or `unresolved` when the registry doesn't expose a repo URL).\n\nNeither the action nor the agent skill calls these at runtime — both vendor the scorer and run locally. The endpoints exist so any third party can build on top of the dashboard without a network round-trip becoming a critical-path dependency.\n\n## Roadmap (high-level)\n\nSee `/roadmap` in the running app or the per-version `tasks/` folders for the full picture.\n\nVersions are sequenced cheap-first so the highest-impact small additions don't get gated on heavy infra:\n\n- **0.7.0 — maintainer ownership + at-scale discovery**: OAuth opt-out / claim flow for maintainers + at-scale package overlay (per-registry leaderboards + userscript that renders the badge inline on npmjs.com / PyPI / crates.io).\n- **1.0.0 — production cut**: Postgres migration for concurrent writers + auto-discovered crawl (target 10k repos) + benchmark harness that derives per-model weights from measured agent success. From here on, breaking API changes require a MAJOR bump.\n\n## Defensibility\n\nThe score isn't defensible. The **evaluation harness + the cross-forge dataset + the maintainer network** are. Open-source the harness, publish the weights, keep the data + dashboard + badge network as the product.\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n\n## Contributing\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for setup, branch/commit style, the PR description template, and the changelog discipline.\n\n## Sponsor\n\nIf this project is useful to you, consider sponsoring its development: [github.com/sponsors/hsnice16](https://github.com/sponsors/hsnice16).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhsnice16%2Fagent-friendly-code","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhsnice16%2Fagent-friendly-code","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhsnice16%2Fagent-friendly-code/lists"}