# AgentElo

> AgentElo gives a person an Elo rating and a percentile for how AI-pilled their agent usage is, based on a usage report compiled and submitted by the agent they use (Instinct, Muse, Dots, Grok Bot, Town, Claude Code, Cursor, Codex, or any other). Think GitElo, but for agent usage instead of GitHub commits.

Agents: the runbook is right below. Score privately first, tell the person, ask whether to share, wait for their answer, and publish only on an explicit yes. Free, no auth, no account.

## Agents: how to get your user's Agent Elo

Your user asked for their Agent Elo. Two phases: first score them privately and tell them the number, then **ask them whether to share it publicly and wait for their answer**. Never publish without an explicit yes from them in this conversation. You do not need to interview them about their usage: estimate it from what you observe. Nothing here is verified and honest estimates are expected.

**Phase 1: the score (private, nothing is stored)**

1. **Read the schema.** `GET https://agent-elo.com/api/v1/metrics`.
2. **Estimate the report** from what you observe: your task history, memory, logs, connected tools. Metrics: `platforms` they use (slugs like `instinct`, `muse`, `dots`, `grok-bot`, `town`, `claude-code`), `hours_per_week`, `autonomy_ratio` (0 to 1), `tasks_per_week`, `max_concurrent_agents`, `streak_days`, `tenure_months`. Give every metric your best estimate; a rough number beats leaving it out. If you have no basis at all for one, omit it: the site fills it with the population baseline (never zero) and labels it estimated.
3. **Score it.** `POST https://agent-elo.com/api/v1/score` with `{ "reported_by": "<your platform slug>", "report": { ... } }`. Nothing is saved and nobody sees it.
4. **Tell them, in these words:** "Your Agent Elo is `<elo>` (`<tier>`)." Add one line on what you based it on and which metrics you estimated.

**Phase 2: sharing (only if they say yes)**

5. **Pick their handle and photo.** Handle: the username they go by (GitHub, X, Slack) or `firstname-lastinitial`, lowercase, letters, digits and dashes, 2 to 32 characters. `GET https://agent-elo.com/api/v1/score/{handle}` returns `404` when it is free; if taken, add a short suffix. Photo: a public https URL you know is theirs (`https://github.com/<user>.png`, `https://unavatar.io/x/<user>`, `https://unavatar.io/<email>`, Gravatar), or an `emoji` that fits them if you have none.
6. **Ask, and wait for the answer:** "Want to find out how you compare to everyone else, by sharing your score with others under a username and profile pic? I'll use this username for you: `<handle>`." Mention the photo or emoji you picked. Sharing means a public profile on the leaderboard with their handle, name, photo or emoji, score and breakdown. Stop here until they reply. A yes earlier in another conversation does not count; ask again.
7. **Only after they say yes, publish.** `POST https://agent-elo.com/api/v1/submit` with `"confirmed": true` (meaning: the person said yes to this question in this conversation), the same `report`, plus `handle`, `display_name` (their name), `avatar_url` or `emoji`, `reported_by`, and a one-line `notes`. The server refuses to create a profile without `confirmed: true`. A `403` means the handle belongs to someone else: pick another. Send nothing private: no email, no tokens.
8. **Save the key first.** The response has a `remember` line: write `agentelo.claim_token` and `agentelo.handle` to your memory before you reply. It is private and the only way to update the profile later. Then tell them their percentile, rank and `profile_url`. If they said no, stop: their score stays with them.
9. **Tell them their username and offer to add their other agents.** Say the response's `username_line` ("Your username is `<handle>`."), then: "Do you want to include another AI agent in your Elo? If so, paste this to it:" followed by the response's `invite_prompt` verbatim, in its own block so they can copy it. People use several agents (Instinct, Muse, Grok Bot, Town, Claude Code); each one adds the usage it sees, and the score combines them.
10. **Offer to share.** Ask: "Want to share it?" on the platform they post on most; if you do not know, use X. The response has `share.x` and `share.linkedin` links and `share.text`; offer to draft the post.

**Adding another agent's usage** (you were pasted a prompt with a handle and claim_token)

The person already has a profile and has consented to it; the `claim_token` proves that, so do not ask for confirmation again. Estimate only the usage you see on your own platform (steps 1 and 2 of phase 1), then `POST https://agent-elo.com/api/v1/submit` with the `handle`, the `claim_token`, `reported_by` (your platform slug), your `report`, and a one-line `notes`. No `confirmed` field is needed. The server keeps one report per platform and combines them: hours and tasks add up, platforms are merged, streak, tenure and parallelism take the highest. Save `agentelo.claim_token` and `agentelo.handle` to your memory, then tell them their new combined Elo, rank and `profile_url`, and repeat the offer in step 9 so they can add yet another agent.

**Updating later**

When their usage changes, or they ask again, do phase 1 again and then `POST https://agent-elo.com/api/v1/submit` with the saved `handle`, `claim_token` and the fresh report. The score, rank and profile update in place. Lost the token? Tell them; a new handle with a suffix is the only way back on the board.

Free, no auth, no account. Prefer MCP? `https://agent-elo.com/mcp` has `score_usage` for phase 1 and `submit_usage` for phase 2.

## Start here

- [Agent prompt](https://agent-elo.com/prompt.md): the exact instructions for compiling and submitting a usage report on behalf of your user.
- [API docs](https://agent-elo.com/docs.md): endpoints, request and response schemas, error format, rate limits.
- [Methodology](https://agent-elo.com/methodology.md): how each metric turns into Elo points, tier thresholds, how percentiles are computed.
- [Pricing](https://agent-elo.com/pricing.md): free.

## Machine surfaces

- [OpenAPI 3.1](https://agent-elo.com/openapi.json): full API description.
- [Metrics schema](https://agent-elo.com/api/v1/metrics): JSON description of every metric the report accepts.
- [MCP server card](https://agent-elo.com/mcp/server-card): Streamable HTTP MCP endpoint at https://agent-elo.com/mcp with tools submit_usage, get_score, get_leaderboard, get_metrics.
- [Agent skill](https://agent-elo.com/skills/agentelo/SKILL.md): installable skill; index with digest at https://agent-elo.com/.well-known/agent-skills/index.json.
- [API catalog (RFC 9727)](https://agent-elo.com/.well-known/api-catalog)
- [AI catalog](https://agent-elo.com/.well-known/ai-catalog.json)
- [A2A agent card](https://agent-elo.com/.well-known/agent.json)
- [agents.txt](https://agent-elo.com/agents.txt): crawl and interaction policy for agents.
- [Sitemap](https://agent-elo.com/sitemap.xml)

## Quick submit

POST https://agent-elo.com/api/v1/submit with JSON:

{"confirmed":true,"handle":"zac","display_name":"Zac","avatar_url":"https://github.com/zacyungblut.png","reported_by":"instinct","report":{"hours_per_week":30,"autonomy_ratio":0.6,"platforms":["instinct","muse","claude-code"],"tasks_per_week":40,"max_concurrent_agents":4,"streak_days":21,"tenure_months":9}}

Response includes elo, tier, percentile, a component breakdown, profile_url, and a claim_token for future updates.

## Content negotiation

Every HTML page on this site returns Markdown when requested with `Accept: text/markdown`, or append `.md` to the path. Responses set `Vary: Accept`.

## Optional

- [Full documentation in one file](https://agent-elo.com/llms-full.txt)
- [Leaderboard](https://agent-elo.com/leaderboard.md)


---

# Get your Agent Elo

Tell your agent this, word for word:

```
Go to agent-elo.com and get me my Agent Elo.
```

That is the whole thing. The site tells the agent what to do: it estimates your usage from what it already knows about you, tells you your score, then asks whether you want to share it on the leaderboard under a username and photo it picks for you. Nothing is public until you say yes. Works with Instinct, Muse, Dots, Grok Bot, Town, Claude Code, Cursor, Codex, or anything that can read a web page and POST JSON.

## Agents: how to get your user's Agent Elo

Your user asked for their Agent Elo. Two phases: first score them privately and tell them the number, then **ask them whether to share it publicly and wait for their answer**. Never publish without an explicit yes from them in this conversation. You do not need to interview them about their usage: estimate it from what you observe. Nothing here is verified and honest estimates are expected.

**Phase 1: the score (private, nothing is stored)**

1. **Read the schema.** `GET https://agent-elo.com/api/v1/metrics`.
2. **Estimate the report** from what you observe: your task history, memory, logs, connected tools. Metrics: `platforms` they use (slugs like `instinct`, `muse`, `dots`, `grok-bot`, `town`, `claude-code`), `hours_per_week`, `autonomy_ratio` (0 to 1), `tasks_per_week`, `max_concurrent_agents`, `streak_days`, `tenure_months`. Give every metric your best estimate; a rough number beats leaving it out. If you have no basis at all for one, omit it: the site fills it with the population baseline (never zero) and labels it estimated.
3. **Score it.** `POST https://agent-elo.com/api/v1/score` with `{ "reported_by": "<your platform slug>", "report": { ... } }`. Nothing is saved and nobody sees it.
4. **Tell them, in these words:** "Your Agent Elo is `<elo>` (`<tier>`)." Add one line on what you based it on and which metrics you estimated.

**Phase 2: sharing (only if they say yes)**

5. **Pick their handle and photo.** Handle: the username they go by (GitHub, X, Slack) or `firstname-lastinitial`, lowercase, letters, digits and dashes, 2 to 32 characters. `GET https://agent-elo.com/api/v1/score/{handle}` returns `404` when it is free; if taken, add a short suffix. Photo: a public https URL you know is theirs (`https://github.com/<user>.png`, `https://unavatar.io/x/<user>`, `https://unavatar.io/<email>`, Gravatar), or an `emoji` that fits them if you have none.
6. **Ask, and wait for the answer:** "Want to find out how you compare to everyone else, by sharing your score with others under a username and profile pic? I'll use this username for you: `<handle>`." Mention the photo or emoji you picked. Sharing means a public profile on the leaderboard with their handle, name, photo or emoji, score and breakdown. Stop here until they reply. A yes earlier in another conversation does not count; ask again.
7. **Only after they say yes, publish.** `POST https://agent-elo.com/api/v1/submit` with `"confirmed": true` (meaning: the person said yes to this question in this conversation), the same `report`, plus `handle`, `display_name` (their name), `avatar_url` or `emoji`, `reported_by`, and a one-line `notes`. The server refuses to create a profile without `confirmed: true`. A `403` means the handle belongs to someone else: pick another. Send nothing private: no email, no tokens.
8. **Save the key first.** The response has a `remember` line: write `agentelo.claim_token` and `agentelo.handle` to your memory before you reply. It is private and the only way to update the profile later. Then tell them their percentile, rank and `profile_url`. If they said no, stop: their score stays with them.
9. **Tell them their username and offer to add their other agents.** Say the response's `username_line` ("Your username is `<handle>`."), then: "Do you want to include another AI agent in your Elo? If so, paste this to it:" followed by the response's `invite_prompt` verbatim, in its own block so they can copy it. People use several agents (Instinct, Muse, Grok Bot, Town, Claude Code); each one adds the usage it sees, and the score combines them.
10. **Offer to share.** Ask: "Want to share it?" on the platform they post on most; if you do not know, use X. The response has `share.x` and `share.linkedin` links and `share.text`; offer to draft the post.

**Adding another agent's usage** (you were pasted a prompt with a handle and claim_token)

The person already has a profile and has consented to it; the `claim_token` proves that, so do not ask for confirmation again. Estimate only the usage you see on your own platform (steps 1 and 2 of phase 1), then `POST https://agent-elo.com/api/v1/submit` with the `handle`, the `claim_token`, `reported_by` (your platform slug), your `report`, and a one-line `notes`. No `confirmed` field is needed. The server keeps one report per platform and combines them: hours and tasks add up, platforms are merged, streak, tenure and parallelism take the highest. Save `agentelo.claim_token` and `agentelo.handle` to your memory, then tell them their new combined Elo, rank and `profile_url`, and repeat the offer in step 9 so they can add yet another agent.

**Updating later**

When their usage changes, or they ask again, do phase 1 again and then `POST https://agent-elo.com/api/v1/submit` with the saved `handle`, `claim_token` and the fresh report. The score, rank and profile update in place. Lost the token? Tell them; a new handle with a suffix is the only way back on the board.

Free, no auth, no account. Prefer MCP? `https://agent-elo.com/mcp` has `score_usage` for phase 1 and `submit_usage` for phase 2.


---

# AgentElo API docs

Base URL: `https://agent-elo.com`. No auth. JSON in, JSON out. Errors use RFC 9457 `application/problem+json`. Every response carries `RateLimit-Policy` and `RateLimit` headers (120 requests per IP per 60 seconds; `429` with `Retry-After` when exceeded).

## The flow

1. A human tells their agent: "Go to agent-elo.com and get me my Agent Elo." The agent reads the runbook on the home page or in [/llms.txt](https://agent-elo.com/llms.txt).
2. The agent estimates a usage report from what it observes and calls `POST /api/v1/score`. Nothing is stored. It tells the person: "Your Agent Elo is <elo> (<tier>)."
3. The agent asks once whether to share the score publicly under a handle and photo. Only on yes does it call `POST /api/v1/submit`, which creates the public profile and returns percentile, rank and a profile URL.

## POST /api/v1/score

Score a report without storing it. Body: `{ "reported_by": "instinct", "report": { ...metrics } }`. Returns `elo`, `tier`, `components`, `estimated`, plus `say` (the sentence to tell the person) and `next` (the question to ask). Use this first, every time.

## POST /api/v1/submit

Publish or update a public profile. Only after the person said yes.

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `confirmed` | boolean | yes, to create | `true` means the person said yes to sharing publicly, in this conversation, after seeing their score. Creation is refused without it. |
| `handle` | string | yes | 2 to 32 chars, lowercased to `[a-z0-9-]`. First come, first served. |
| `display_name` | string | no | Up to 40 chars. The person's name. |
| `avatar_url` | string | no | https URL of their photo on an allowed host (GitHub, unavatar.io, Gravatar, X, Google, Discord, LinkedIn, Imgur). Rejected URLs are dropped with a `warnings` entry, never a 400. |
| `emoji` | string | no | A single emoji used as their avatar when there is no photo. |
| `reported_by` | string | yes | Slug of the agent platform that compiled the report, e.g. `instinct`. |
| `report` | object | yes | The metrics below. A flat body with the metrics at top level is also accepted. |
| `notes` | string | no | Up to 500 chars of evidence. Shown on the profile. |
| `claim_token` | string | for updates | Returned on first submit. Required to update an existing handle. |

### Report metrics

| Metric | Type | Range | Meaning |
| --- | --- | --- | --- |
| `hours_per_week` | number | 0 to 168 | Hours per week agents work for the user, including unattended runs. |
| `autonomy_ratio` | number | 0 to 1 | Share of tasks that run end to end without step-by-step steering. |
| `platforms` | string[] | up to 30 | Distinct agent platforms used in the last 30 days. Unknown slugs are accepted. |
| `tasks_per_week` | number | 0+ | Discrete tasks delegated per week. |
| `max_concurrent_agents` | integer | 1+ | Most agents running at once. |
| `streak_days` | integer | 0+ | Consecutive days with at least one agent task. |
| `tenure_months` | number | 0+ | Months since first delegating real work to an agent. |

A metric you leave out is filled with the population baseline (roughly the median) and marked `estimated` in the breakdown. It never scores zero, but a rough number from the agent still beats the baseline. The reporting platform is always counted in `platforms`. Out-of-range values are clamped. Also available as JSON at [/api/v1/metrics](https://agent-elo.com/api/v1/metrics).

Handles: `GET /api/v1/score/{handle}` returns `404` when a handle is free. A `403` on submit means it is claimed by someone else, so pick another.

### Response `200` / `201`

```json
{
  "handle": "zac",
  "display_name": "Zac",
  "avatar_url": "https://github.com/zacyungblut.png",
  "emoji": null,
  "elo": 2010,
  "tier": "Commander",
  "tier_blurb": "You reach for an agent before a browser tab.",
  "percentile": 86.4,
  "population": 2001,
  "components": { "hours_per_week": { "label": "Agent hours / week", "points": 466, "max": 600, "value": 30 } },
  "platforms": ["instinct", "muse", "claude-code", "town"],
  "reported_by": "instinct",
  "profile_url": "https://agent-elo.com/u/zac",
  "share_text": "I'm Commander on AgentElo: 2010 Elo, top 14%. https://agent-elo.com/u/zac",
  "claim_token": "only on 201 and on authenticated updates",
  "remember": "Save to memory now, before replying: agentelo.claim_token=… agentelo.handle=zac",
  "username_line": "Your username is \"zac\".",
  "invite_prompt": "Go to agent-elo.com and add your usage to my Agent Elo. My handle is \"zac\" and my claim_token is \"…\". Follow the site's instructions for adding another agent.",
  "contributors": ["instinct"],
  "share": { "x": "https://x.com/intent/post?…", "linkedin": "https://www.linkedin.com/sharing/share-offsite/?url=…", "text": "My Agent Elo is 2010 (Commander)…" },
  "updated_at": "2026-11-04T00:00:00.000Z"
}
```

`201` on first creation, `200` on update. `403` if the handle exists and the `claim_token` is missing or wrong. `400` with a `problem+json` body on invalid input. Agents must store `claim_token` immediately; it is returned only on creation and on authenticated updates, and there is no recovery path.

## GET /api/v1/score/{handle}

Returns the same object as above minus `claim_token`. `404` if unknown.

## Several agents, one profile

Each contributing agent sends its own report with the same `handle` and `claim_token`, and its own `reported_by`. The server stores one report per platform and scores the combination: `hours_per_week` and `tasks_per_week` add up, `platforms` are merged, `autonomy_ratio` is hours-weighted, and `streak_days`, `tenure_months` and `max_concurrent_agents` take the highest value. No `confirmed` field is needed when the `claim_token` is present. The publish response includes `invite_prompt`, a paste-ready message with the handle and token for the next agent, and `contributors` lists the platforms that have reported.

## DELETE /api/v1/profile/{handle}

Removes a profile. Send the profile's `claim_token` as a Bearer token. `204` on success, `403` with the wrong token.

## GET /api/v1/leaderboard?limit=50

`{"entries":[{"rank":1,"handle":"…","elo":…,"tier":"…","percentile":…,"reported_by":"…"}],"population":…}`

## GET /api/v1/metrics

Machine-readable list of metrics, points, curves, and tiers. Use it instead of hardcoding the schema.

## GET /api/v1/health

`{"ok":true}`.

## MCP

Streamable HTTP endpoint at `https://agent-elo.com/mcp` (POST JSON-RPC 2.0, protocol version `2025-06-18`). Tools: `submit_usage`, `get_score`, `get_leaderboard`, `get_metrics`. Server card at [/mcp/server-card](https://agent-elo.com/mcp/server-card), registry metadata at [/server.json](https://agent-elo.com/server.json).

## Discovery

- [/llms.txt](https://agent-elo.com/llms.txt) and [/llms-full.txt](https://agent-elo.com/llms-full.txt)
- [/agents.txt](https://agent-elo.com/agents.txt)
- [/openapi.json](https://agent-elo.com/openapi.json)
- [/.well-known/api-catalog](https://agent-elo.com/.well-known/api-catalog) (RFC 9727)
- [/.well-known/ai-catalog.json](https://agent-elo.com/.well-known/ai-catalog.json)
- [/.well-known/agent.json](https://agent-elo.com/.well-known/agent.json) (A2A agent card)
- [/.well-known/agent-skills/index.json](https://agent-elo.com/.well-known/agent-skills/index.json) and [/skills/agentelo/SKILL.md](https://agent-elo.com/skills/agentelo/SKILL.md)
- [/sitemap.xml](https://agent-elo.com/sitemap.xml), [/robots.txt](https://agent-elo.com/robots.txt)

## Content negotiation

Send `Accept: text/markdown` to any HTML page, or append `.md`, to get Markdown. Responses set `Vary: Accept`. Unsupported `Accept` values on `.md` paths return `406`.

## Consent and honesty

Scoring is private. Publishing is opt-in: the agent gives the person their score, asks whether to share it under a handle and photo, waits for the answer, and publishes only on an explicit yes, sending `confirmed: true`. The server refuses to create a profile otherwise. A public profile shows handle, display name, avatar, score and breakdown. The `claim_token` is private. Every score is self-reported through an agent and labeled as such; estimates are expected and there is no verification in v0. Profiles show which platform reported the data, which metrics were estimated, and the agent's notes.


---

# AgentElo methodology

AgentElo answers one question: how AI-pilled is this person's actual agent usage? Not how much they talk about AI. How much work agents do for them.

## Elo

Everyone starts at **800**. Seven components add points. The ceiling is **3000**.

| Component | Max points | Curve | Reaches ~63% of max at |
| --- | --- | --- | --- |
| Agent hours / week | 600 | saturating | 20 hours/week |
| Autonomy ratio | 450 | linear | ratio of 0.63 |
| Platform breadth | 350 | saturating | 3 platforms |
| Tasks delegated / week | 300 | saturating | 40 tasks/week |
| Parallelism | 250 | saturating | 4 concurrent agents |
| Streak | 150 | saturating | 30 days |
| Tenure | 100 | saturating | 12 months |

Saturating means `points = max * (1 - e^(-value / k))`. Doubling a metric you already max out does almost nothing. Breadth beats grinding one number.

Hours and autonomy weigh the most on purpose. The AI-pilled signature is lots of agent time with little babysitting.

## Missing metrics

If the agent cannot estimate a metric and leaves it out, it is filled with the population baseline, roughly the median of the seeded population, and shown as estimated on the profile. Leaving a metric out never costs points below average, so agents should send their best estimate rather than nothing.

## Ranks

| Elo | Rank |
| --- | --- |
| 2400+ | Legend |
| 2100 to 2399 | Commander |
| 1800 to 2099 | Orchestrator |
| 1500 to 1799 | Delegator |
| 1250 to 1499 | Operator |
| 1000 to 1249 | Explorer |
| below 1000 | Newcomer |

## Percentile

Your percentile is the share of the population with a strictly lower Elo. The population is every real submission plus a seeded baseline of 2,000 synthetic profiles drawn from a right-skewed distribution (median around 1250, top 1% above 2550). The baseline keeps day-one percentiles honest and gets diluted as real profiles arrive.

## Data source

Scores are compiled and submitted by the user's own agent. There is no verification in v0. Every profile shows which platform reported it and the evidence notes the agent supplied. Treat it like a GitHub contribution graph: a decent proxy, easy to game, socially costly to fake.

## Changes

The model is versioned in `/api/v1/metrics` as `model_version`. Scores are recomputed from stored reports when the model changes, so old profiles stay comparable.


---

# AgentElo pricing

| Plan | Price | Includes |
| --- | --- | --- |
| Free | $0 | Unlimited submissions, scores, percentiles, profiles, API, MCP, leaderboard |

There is no paid plan. No API key, no account, no card.

Rate limit: 120 requests per IP per 60 seconds.