huggingface/agent-usage

1---2pretty_name: Agent Usage on the Hugging Face Hub3tags:4  - analytics5  - agents6configs:7  - config_name: monthly8    default: true9    data_files: data/monthly/*.parquet10  - config_name: daily11    data_files: data/daily/*.parquet12---13 14# Agent Usage on the Hugging Face Hub15 16**Coding agents are real users of the Hugging Face Hub.** Claude Code, Codex, Cursor, and a growing list of harnesses are searching for models, building and pushing datasets, training models on [Jobs](https://huggingface.co/docs/hub/jobs), spinning up Spaces — tens of millions of requests so far ([hf CLI for agents](https://huggingface.co/blog/hf-cli-for-agents)). Now there's public data on which ones.17 18Requests made through the `huggingface_hub` library (including the `hf` CLI) carry an [`agent/<name>` User-Agent token](https://huggingface.co/docs/hub/agents-overview) identifying the harness. This dataset publishes **each harness's share of that agent-attributed traffic**, month by month and day by day, updated by a scheduled [HF Job](https://huggingface.co/docs/hub/jobs).19 20![Current leaderboard](assets/leaderboard.png)21 22_Named harnesses ranked by share of requests, data through **2026-08** · updated 2026-09-07. The **Dataset Viewer** at the top of this page lets you browse, sort, and filter both tables — no code needed._23 24## What you can see25 26- **Who's calling the Hub** — the monthly leaderboard of named harnesses, and how it shifts as new tools launch and register.27- **Usage styles** — compare request share with user share. An agent with 30% of requests but 8% of users is a small crowd running heavy automated pipelines; the reverse means many users, each doing a little.28- **Day-by-day detail** — the `daily` config picks up what monthly numbers smooth over: launch spikes, growth curves, weekday-vs-weekend patterns.29 30## Get your harness on the board31 32If you build a harness, register it to make sure your agent isn't missed — unregistered tools are counted only as `unknown`.33 34Attribution is automatic: `huggingface_hub` detects registered harnesses from environment variables and reports them in the User-Agent. To register, follow [Register your agent harness](https://huggingface.co/docs/hub/agents-overview#register-your-agent-harness) — a Pull Request adding your tool to [`agent-harnesses.ts`](https://github.com/huggingface/huggingface.js/blob/main/packages/tasks/src/agent-harnesses.ts). No release is needed on either side: installed clients refresh the registry within a day, and your harness appears from the next monthly snapshot.35 36Only traffic through the Python `huggingface_hub` library (including the `hf` CLI) is attributed; direct HTTP calls to the Hub API are not counted. To confirm detection works, run inside your harness:37 38```bash39python -c "from huggingface_hub.utils import build_hf_headers; print(build_hf_headers()['user-agent'])"40# should contain agent/<your-id>41```42 43## Columns44 45| column          | description                                                                                                  |46| --------------- | ------------------------------------------------------------------------------------------------------------ |47| `month` / `day` | period the share is computed over                                                                            |48| `agent`         | harness name from the `agent/<name>` token; `unknown` = token present but no registered name                 |49| `pct_requests`  | harness's share of agent-attributed `huggingface_hub` requests in the period (0–100; sums to 100 per period) |50| `pct_users`     | same, for distinct authenticated users — someone using two harnesses counts once for each                    |51 52## Loading programmatically53 54```python55from datasets import load_dataset56 57monthly = load_dataset("huggingface/agent-usage", "monthly", split="train")58```59 60```sql61-- DuckDB: full monthly history in one query62SELECT month, agent, pct_requests63FROM 'hf://datasets/huggingface/agent-usage/data/monthly/*.parquet'64WHERE agent != 'unknown'65ORDER BY month, pct_requests DESC;66```67 68```python69import polars as pl70 71daily = pl.scan_parquet("hf://datasets/huggingface/agent-usage/data/daily/*.parquet")72```73 74New months append as new parquet files, so these queries always return the full history unchanged.75 76## Reading the data77 78- **This measures Hub usage, not overall agent popularity.** A widely used tool that rarely touches the Hugging Face Hub will rank low here.79- **Shares are zero-sum.** A falling share doesn't mean falling usage — total agent traffic is growing, so a harness can double its requests while its share shrinks.80- **Start month-over-month comparisons from May 2026.** The `agent/` token rolled out April 3 and harnesses added detection at different times, so April reflects the rollout, not relative usage.81- **Smooth daily shares** with a 7-day rolling mean — weekends and small denominators make single days noisy.82- **Attribution is self-declared** (a User-Agent token set by the client library) and covers Python-library traffic only.83 84_Built by [`build_local.py`](./build_local.py) (bundled in this repo) on a scheduled HF Job — only relative shares are published._85