Agent Friendly Code

How Agent Friendly Code scores repos

How we work out each score, what we check, and what we can't check yet.

Weights last changed: 2026-08-25 (v0.7.0, Kimi CLI weight profile added).

Weights from docs, not yet tested

Scores come from file checks: whether a file exists, and how long it is. No agent is run. Each agent's weights follow its own docs (Sources, under each agent) but aren't yet measured against real runs; that is v1.0.0 on the roadmap. Treat scores as a guide, not a verdict.

Score formula

per-agent score = Σ(check.pass × agent.weight[check]) / Σ(agent.weight) × 100
overall         = mean(per-agent scores)
improvement     = closing a gap unlocks  (1 - pass) × weight / Σweight × 100  points

check.pass is a number from 0 to 1, so a check can pass in part: a short README gets 0.3, a long one 1.0.

Checks (16)

File names can be any case: readme.md and README.MD both count as a README.

  • An instructions file for agents, with real content.
    Improve: Add an AGENTS.md covering project goals, layout, setup commands, and conventions. Aim for 800+ chars of real guidance (not boilerplate).
  • Cursor's instructions: `.cursor/rules/*.mdc`, or the legacy `.cursorrules`.
    Improve: Add `.cursor/rules/*.mdc` files describing how Cursor should work in this repo (architecture, conventions, naming). The legacy `.cursorrules` file is still read but is deprecated.
  • GEMINI.md
    gemini_md
    Gemini CLI's instructions file, read on every prompt.
    Improve: Add a GEMINI.md at the repo root covering project goals, layout, setup commands, and conventions. Aim for 800+ chars of real guidance (not boilerplate).
  • .openhands/setup.sh
    openhands_setup
    `.openhands/setup.sh`, which OpenHands runs at session start to set up the dev environment.
    Improve: Add a `.openhands/setup.sh` that installs dependencies and prepares the project so OpenHands can run tests and lints out of the box.
  • .aider.conf.yml
    aider_conf
    `.aider.conf.yml` (or `.yaml`): Aider's repo config — model, lint and test commands.
    Improve: Add a `.aider.conf.yml` at the repo root pinning Aider's `test-cmd` and `lint-cmd` so it auto-runs them after edits.
  • README
    readme
    A README with enough detail for the agent to learn the project.
    Improve: Expand your README to cover what the project does, how to install, the common commands, and the high-level layout.
  • Tests the agent can run to check its changes.
    Improve: Add a tests/ (or test/, __tests__/, spec/) directory with runnable tests. Document how to run them in AGENTS.md.
  • A CI pipeline the agent can read and run locally.
    Improve: Add a CI workflow (e.g. .github/workflows/ci.yml or .gitlab-ci.yml) that runs tests + linter on every PR.
  • A linter, so the agent gets style feedback right away instead of guessing.
    Improve: Configure a linter/formatter (ESLint+Prettier, Biome, Ruff, rustfmt+clippy, golangci-lint) and commit the config.
  • Dependency manifest
    deps_manifest
    A dependency manifest, so the agent can reproduce the environment.
    Improve: Commit a proper manifest (package.json, pyproject.toml, Cargo.toml, go.mod, etc.) plus a lockfile.
  • One-command setup the agent can run: Makefile, devcontainer, Nix or Docker.
    Improve: Add a Makefile or devcontainer or Dockerfile so the agent can set up the project in one command.
  • Static types let the agent check call sites without running code.
    Improve: Add a type config (tsconfig.json for JS/TS, mypy.ini or pyrightconfig.json for Python). Rust/Go/JVM/Scala/Swift/C#/OCaml/Haskell/Zig are typed by default.
  • A license, so it's clear what may be done with the code.
    Improve: Add a LICENSE (or COPYING) file — MIT, Apache-2.0, BSD, GPL, etc. — at the repo root.
  • CONTRIBUTING guide
    contributing
    A contribution workflow the agent can follow.
    Improve: Add CONTRIBUTING.md describing branch naming, commit style, test commands, and the PR process.
  • Pre-commit hooks catch problems before the agent waits on CI.
    Improve: Set up pre-commit (.pre-commit-config.yaml), husky, or lefthook to run format+lint on every commit.
  • Very large repos strain the agent's context window.
    Improve: If possible, split into smaller modules or carve out a focused entry path. Document where to start in AGENTS.md.

AI agents and their weights (9)

  • Claude Code
    Loads CLAUDE.md at the start of every conversation per Anthropic's memory docs, or AGENTS.md when there is no CLAUDE.md, so AGENTS.md / CLAUDE.md and a fast test loop carry the most weight.
    Sources:code.claude.com/memory
    Weights
    tests            1.00
agents_md        1.00
dev_env          0.90
readme           0.70
deps_manifest    0.70
linter           0.60
type_config      0.60
ci               0.50
size             0.50
pre_commit       0.40
contributing     0.40
license          0.30
gemini_md        0.00
aider_conf       0.00
cursor_rules     0.00
openhands_setup  0.00
  • Cursor
    Per Cursor's Rules docs, reads `.cursor/rules/*.mdc` and AGENTS.md as the canonical repo-side input. Type config and a clean README still aid the codebase index but aren't the docs-cited signal.
    Sources:cursor.com/rules
    Weights
    readme           1.00
type_config      1.00
cursor_rules     1.00
linter           0.80
agents_md        0.80
deps_manifest    0.80
tests            0.70
dev_env          0.50
ci               0.40
size             0.40
license          0.30
pre_commit       0.30
contributing     0.30
gemini_md        0.00
aider_conf       0.00
openhands_setup  0.00
  • Devin
    Works in a Linux virtual machine booted from a snapshot that already has the repo cloned and its tools, dependencies, environment variables and secrets set up, then installs, lints, builds and tests like any developer, per Cognition's environment docs. CI config files alone aren't what the docs ask for — a runnable dev environment is.
    Sources:docs.devin.ai/environment
    Weights
    dev_env          1.00
tests            0.90
deps_manifest    0.90
ci               0.70
readme           0.70
size             0.60
agents_md        0.60
linter           0.50
pre_commit       0.50
type_config      0.50
contributing     0.50
license          0.30
gemini_md        0.00
aider_conf       0.00
cursor_rules     0.00
openhands_setup  0.00
  • GPT-5 Codex
    Reads AGENTS.md before doing any work per OpenAI's Codex docs. Hierarchical (per-directory) AGENTS.md and AGENTS.override.md are first-class.
    Sources:learn.chatgpt.com/agents-md
    Weights
    agents_md        0.90
tests            0.80
readme           0.80
ci               0.70
dev_env          0.70
type_config      0.70
deps_manifest    0.70
linter           0.60
size             0.50
pre_commit       0.40
contributing     0.40
license          0.30
gemini_md        0.00
aider_conf       0.00
cursor_rules     0.00
openhands_setup  0.00
  • Kimi CLI
    Reads AGENTS.md as its native instruction surface (root or `.kimi-code/AGENTS.md`) per Moonshot's Kimi Code docs, and `/init` generates one. Its docs name no CLAUDE.md fallback, but the check passes on CLAUDE.md too. Runs shell commands step-by-step under an approval gate rather than a sandbox VM, and dispatches `explore` sub-agents with isolated contexts to map a codebase, so a large tree costs it less than a single-context agent.
    Sources:github.com/agents.md github.com/slash-commands.md
    Weights
    agents_md        1.00
tests            0.90
readme           0.70
dev_env          0.70
deps_manifest    0.70
linter           0.60
type_config      0.60
ci               0.40
size             0.40
pre_commit       0.40
contributing     0.40
license          0.30
gemini_md        0.00
aider_conf       0.00
cursor_rules     0.00
openhands_setup  0.00
  • Gemini CLI
    Reads hierarchical `GEMINI.md` (global → workspace → component-level) at every prompt per Gemini CLI's docs; AGENTS.md is read only when listed in the `context.fileName` setting. The long-context advantage favors repos that split context per directory rather than docs-heavy in general.
    Sources:geminicli.com/gemini-md
    Weights
    gemini_md        1.00
tests            0.90
readme           0.90
type_config      0.90
deps_manifest    0.80
linter           0.70
dev_env          0.70
agents_md        0.70
ci               0.60
size             0.50
pre_commit       0.40
contributing     0.40
license          0.30
aider_conf       0.00
cursor_rules     0.00
openhands_setup  0.00
  • Aider
    Auto-lints on every edit by default; runs the configured test command after edits when `--test-cmd` is set (per Aider's lint/test docs). It doesn't natively read AGENTS.md or CONVENTIONS.md — those load only when wired via `.aider.conf.yml`'s `read:` — so the config file, a green linter, and a declared test command are what translate into successful commits.
    Sources:aider.chat/lint-test.html aider.chat/aider_conf.html
    Weights
    tests            1.00
linter           1.00
aider_conf       1.00
deps_manifest    0.70
readme           0.60
dev_env          0.50
type_config      0.50
size             0.40
ci               0.30
agents_md        0.30
pre_commit       0.30
contributing     0.30
license          0.20
gemini_md        0.00
cursor_rules     0.00
openhands_setup  0.00
  • OpenHands
    Runs in a sandboxed container and executes `.openhands/setup.sh` at session start per OpenHands' repo-customization docs. A root AGENTS.md is the preferred always-on instruction surface; the older `.openhands/microagents/` path has been renamed to Skills (`.agents/skills/`).
    Sources:docs.openhands.dev/repository docs.openhands.dev/skills
    Weights
    ci               1.00
dev_env          1.00
deps_manifest    1.00
openhands_setup  1.00
tests            0.90
size             0.70
readme           0.70
contributing     0.70
linter           0.60
pre_commit       0.60
agents_md        0.50
type_config      0.50
license          0.40
gemini_md        0.00
aider_conf       0.00
cursor_rules     0.00
  • Pi
    Minimal terminal coding harness. Loads `AGENTS.md` (or `CLAUDE.md`) from its agent directory, the working directory and its parent directories, per Pi's configuration docs. It has no built-in sandbox; isolation is left to a container the user runs it in.
    Sources:github.com/configuration.md
    Weights
    agents_md        1.00
tests            0.90
linter           0.80
readme           0.70
deps_manifest    0.70
dev_env          0.60
type_config      0.60
size             0.50
ci               0.40
pre_commit       0.40
contributing     0.30
license          0.20
gemini_md        0.00
aider_conf       0.00
cursor_rules     0.00
openhands_setup  0.00

What we don't check yet

  • Whether tests pass. We only check that they exist.
  • Whether the linter runs without errors.
  • Whether the dev setup (Makefile, Dockerfile) works end to end.
  • Commit history, such as activity or contributor count. Clones are --depth 1 --single-branch, and history says more about a repo's health than about how agents work in it.
  • How well agents do on the repo. That comes with the v1.0.0 benchmark.

Questions

How is the score worked out?
We fetch the latest version of each repo (no history) and run sixteen checks. Twelve matter to every agent: AGENTS.md / CLAUDE.md, CI, tests, README, linter, type config, license, contributing guide, a reproducible dev setup, pre-commit hooks, a dependency list, and codebase size. Four are files only one agent reads: .cursor/rules/*.mdc, GEMINI.md, .openhands/setup.sh, and .aider.conf.yml. Each agent's score is the weighted share of checks passed; the overall score is the average across agents.
Why give each agent its own score?
Because each agent's docs name different files. Claude Code loads CLAUDE.md every session and GPT-5 Codex reads AGENTS.md before any work, so that file counts most for them. Devin works in its own machine, so a runnable dev setup counts more than CI. Cursor reads .cursor/rules/ and AGENTS.md. One number would hide that a repo can suit one agent and not another.
Which AI coding agents do you score for?
Claude Code, Cursor, Devin, GPT-5 Codex, Kimi CLI, Gemini CLI, Aider, OpenHands, and Pi. Each has its own set of weights, in lib/scoring/weights.ts.
Does this test how well agents actually work?
No. Scores come from file checks; no agent is run. The weights follow each agent's docs but aren't yet measured against real runs, so treat scores as a guide.
How can I raise my repo's score?
Add an AGENTS.md or CLAUDE.md that explains the project, runnable tests, CI, a detailed README, linter and type config, a license, a CONTRIBUTING guide, and a one-command dev setup (devcontainer, Dockerfile or Makefile). Each repo's page lists the fixes that help each agent most.
How do I stop pull requests from lowering my score?
Install the GitHub Action (hsnice16/agent-friendly-action). It scores each pull request against its target branch in your CI and posts one comment with what changed. An AGENTS_BADGE_TOKEN secret turns it on; every GitHub repo's page has the workflow to copy.
What is AGENTS.md or CLAUDE.md?
A markdown file at the repo root that tells an AI coding agent what the project is, how to build and test it, and which rules to follow. It is the top check for Pi and Kimi CLI, ties with tests for Claude Code, and helps every other agent.
How often are scores updated?
Every six hours, and whenever the repo list or the scoring rules change.
Which code hosts are supported?
GitHub, GitLab and Bitbucket on the leaderboard, all scored the same way. Live Score takes public GitHub repos for now.