![\"A](\"docs/example.png\")
\n ![\"A](\"docs/recap.png\")
\n\n \n \n
\n ![\"A](\"docs/weekly.png\")
\n ![\"A](\"docs/monthly.png\")
\n
A session · a season · a week · a month. All four belong to a synthetic athlete — no real usage data ships in this repo.
\n\n**Nothing on a card is self-reported.** A hook parses the session transcript for\ntool calls, tokens, diff hunks, recovered errors and moving time. The agent never\ngets to describe its own workout. Works with Claude Code, Codex CLI and Cursor.\n\n## Warm-up: install\n\n```bash\nnpx agentrava setup\n```\n\nCopies itself to `~/.agentrava/app`, registers the MCP server with Claude Code,\nadds the Stop hook, and offers to log your past sessions so the first card you\nsee is one of your own. If Codex CLI or Cursor is installed, it asks before\ntouching either. Idempotent, backs up every file it edits, and reversible:\n\n```bash\nnpx agentrava setup --manual # keep the tools, stop logging every turn\nnpx agentrava setup --auto # put automatic logging back\nnpx agentrava setup --codex # register with Codex CLI without being asked\nnpx agentrava setup --yes # accept every offer, ask nothing\nnpx agentrava setup --uninstall # remove everything (your data is left alone)\nnpx agentrava@latest setup # update\n```\n\nRestart Claude Code, then ask it to \"show my agentrava\". Every script below is\nalso a subcommand — `npx agentrava card --best`, `npx agentrava snap week` —\nand `npx agentrava help` lists them.\n\n**Why it copies itself:** the hook and the server are registered by absolute\npath, and `npx` runs packages from a cache npm can clear at any time. A copy in\n`~/.agentrava/app` keeps working after that. Moving between a clone and the copy\nre-points the existing hook instead of adding a second one.\n\nAny other MCP client works — it speaks stdio:\n\n```json\n{ \"mcpServers\": { \"agentrava\": { \"command\": \"npx\", \"args\": [\"-y\", \"agentrava\"] } } }\n```\n\n**From a clone**, for hacking on it: `git clone https://github.com/lukisimi/agentrava && cd agentrava && node scripts/install.mjs`.\nThe setup then registers the clone itself, and the `node scripts/…` commands in\nthe rest of this page work as written.\n\n## Tools\n\n- **`agentrava`** — start here: every tool with an example, plus your totals and streak.\n- **`snapshot`** — card for the session in progress, measured from the live transcript.\n Takes `photo` (`\"chat\"` uses an image you just pasted), `title` to rename it inline,\n and `share` (`full` · `friends` · `anonymous`) to strip it [before you post it](#before-you-share-one).\n- **`log_activity`** — log a session by hand; unreported fields count as zero.\n- **`recap`** — one card for a whole period: totals, activity heatmap, hour-of-day\n histogram, trophy case, longest streak, biggest session. Optional `from` / `to`.\n- **`weekly_snap`** · **`monthly_snap`** — a week or a month on one card, same size as a session card.\n Take `period` (`this`, `last`, `last7` / `last30`, or a date), `title`, `hide_projects`, and `pick`.\n- **`get_profile`** — career totals, streak, personal records, trophy case.\n- **`rename_session`** · **`rename_project`** · **`list_projects`** — your own names, kept across re-logs.\n- **`list_activities`** · **`leaderboard`** · **`set_athlete`**\n\n## The metaphor\n\n| Strava | Agentrava | Formula |\n|---|---|---|\n| Distance | ground covered | `churn / 100 + tool_calls / 25` km |\n| Elevation | the parts that hurt | `files × 37 + errors × 120 + tests_failed × 45` m |\n| Moving time | session time, idle excluded | gaps over 5 min don't count |\n| Pace | minutes per km | `time / distance` |\n| Suffer score | Effort, 0–100 | cadence, elevation, tokens, retries |\n| Calories | tokens burned | input + cache writes + output |\n| Economy | tokens per km | lower is leaner |\n| Gear | the model | measured, never assumed |\n| — | API cost | priced per message at list rates |\n\nEvery weight is **fitted to real sessions**, not guessed. Churn alone left the\nmedian session at 0.00 km — most sessions read and search far more than they\nwrite — which is why tool calls carry distance too.\n\n## Training science: what the numbers actually mean\n\nThe inputs are measured. The **scales are invented** — 100 lines = 1 km, an error\n= 120 m — chosen so a median session lands near a plausible 4.4 km. That makes\ncards comparable **between your own sessions**, which is what records and the\nleaderboard rest on, and meaningless outside Agentrava.\n\nMeasured across 134 sessions:\n\n| | correlates most with | r |\n|---|---|---|\n| Distance | tool calls | **0.94** |\n| Distance | churn | 0.86 |\n| Elevation | errors recovered | **0.91** |\n| Elevation | files changed | 0.88 |\n\nSo distance is *volume of activity* — 69% of it from the tool-call term — and\nelevation is *friction*, 58% of it from errors. They correlate 0.79 with each\nother: overlapping, but about a third of elevation is information distance\ndoesn't carry, which is what separates a long easy session from a short brutal one.\n\n### Not every failed tool call is friction\n\nAn error is a tool result the client flagged as failed. Sampled across 166 real\nClaude Code errors: 45% a shell command exiting non-zero, 11% bad arguments or a\nmissing file, 7% a browser step, 19% app-level errors from the user's own tools —\nand **12% nothing to do with the agent at all**: the human declining a tool call,\nthe permission layer blocking one, a model or MCP server briefly unavailable.\n\nThose last ones are counted separately (`errors_environmental`) and **left out of\nthe climb**, because 120 m of elevation and a loop in the route should mean work\nthat had to be redone, not a moment where someone hit Escape. Across this store\nthat removed 89 errors and 8 km of climb, and demoted 4 cards from Debug.\n\nThe test, in [`src/errors.js`](src/errors.js), is a phrase list run against the\n**first 300 characters** of the failure text — these failures announce themselves\nin their first line, while a long command output can mention \"rate limit\"\nanywhere. 609 *successful* Cursor tool results contain that phrase and not one of\nthem is a rate limit. Deliberately excluded from the list: `permission denied`\n(a real filesystem failure the agent must work around), a bare `timed out`\n(usually its own command hanging) and `connection refused` (usually a dev server\nit forgot to start).\n\nEach client hides the text somewhere different — Claude Code in the\n`tool_result`, Cursor in `toolFormerData.result`, Codex in a failed item's\n`result` for an MCP call or `stderr` for a shell one. Serialising a whole Codex\nitem instead tested the command line and the id, which counted a session that\nmerely *printed* the word \"rejected\" as a refusal.\n\n**Errors are not a measure of inefficiency.** Their raw count is mostly a size\nmeasurement — 0.87 against tool calls. As a rate (errors per 100 tool calls) they\ncorrelate 0.08 with tokens per line changed and −0.01 with seconds per line\nchanged. Across 78 sessions, a 5× difference in error rate bought 20% more tokens\nper line and 18% *less* time per line: no signal. Elevation honestly means\neventful, not wasteful.\n\n**Raw tokens cannot rank efficiency.** They correlate 0.72 with distance, so the\nnumber mostly says how big a session was. Economy (tokens per km) correlates 0.08\nwith distance — size-independent, and therefore actually comparable. It measures\ntoken cost per unit of *volume*, not of *value*: a session that finds the right\nanswer in five calls scores badly on it.\n\n**None of this measures whether the work was any good.** A session that flails for\n800 tool calls outscores one that fixes the bug in five. Nothing in a transcript\nreliably encodes outcome — that's a ceiling, not a tuning problem.\n\n## The route and the climb profile\n\n**The route map** is a random walk seeded by the activity id, so a card always\nredraws identically. Two things in it are real: its length and density come from\ntool calls, and **every error you recovered from draws as a loop** — the trace\nshows where you went in circles.\n\n**The climb profile** under it is cumulative elevation: flat where the session ran\nsmoothly, stepping up wherever a file was written or an error recovered, bucketed\nby moving time so an idle gap doesn't collapse it. The area under the curve is the\nelevation figure on the card.\n\nThat strip was decoration until recently — a seeded random walk reading no session\ndata at all, the same label over pure noise. Sessions with fewer than three climb\nevents now get **no strip at all** rather than an invented one. 81% have a profile.\n\n## Weekly and Monthly Snap\n\n```bash\nnode scripts/snap.mjs week # this calendar week so far\nnode scripts/snap.mjs week last # the previous calendar week\nnode scripts/snap.mjs week last7 # rolling seven days, ending today\nnode scripts/snap.mjs month # this calendar month so far\nnode scripts/snap.mjs month last30 # rolling thirty days (14d, 90d… also work)\nnode scripts/snap.mjs month 2026-08 --pick 086f7bf6 # feature a session you chose\nnode scripts/snap.mjs week --title \"Shipped the new onboarding\" --hide-projects\n```\n\n**Calendar or rolling.** A calendar week shared on a Wednesday is a stub — it\nsays \"this week so far\" and two days are empty. `last7` and `last30` are always\nwhole windows ending today, which is usually what you want to post. Calendar\nperiods stay the default because streaks, months and heatmaps are calendar\nthings. Rolling cards label themselves by range and by weekday, since a rolling\nweek does not start on a Monday.\n\nBoth are **1080×1350, the same frame as a session card**, so a snap and a card sit\nside by side in a feed. A six-row month is the tightest case and still clears the\nfooter.\n\n**Weekly** — agent time per day, sessions / active days / projects, tool calls,\nestimated cost, and the longest session. **Monthly** — a Monday-first heatmap,\nthe same headline counts, the top three projects by time, and a featured session.\n\nWhat makes the numbers hold together:\n\n- **Daily buckets are recorded, not inferred.** Both parsers credit each stretch\n of moving time to the local day it happened, splitting at midnight, so a session\n from 23:50 to 00:05 counts 10 minutes on one day and 5 on the next. Every bar\n and heatmap cell comes from those buckets, and so does Active Days — seven bars\n can't sit next to a five-day headline.\n- **A session crossing a period boundary appears in both**, with its time\n apportioned. Tool calls and cost have no per-day record, so they are apportioned\n by the same time share.\n- **\"Agent time\" is summed across sessions.** Nine agents running in parallel for\n five hours is 45 hours of agent time on one day. The card says so under the\n chart; it is not your working hours.\n- **Cost says when it is partial** — `partial · 38 of 40 priced` — and reads\n \"not recorded\" rather than $0 when nothing could be priced.\n- **\"Month's pick · Selected by you\" appears only when you picked it.** Otherwise\n the feature is labelled \"Longest session\", which is what it is.\n- **An unfinished period says so** — \"This week so far\".\n- **Nothing is inferred about outcome.** A `--title` is yours to write; the card\n never claims anything shipped.\n\n## Badges\n\nEarnable, not participation trophies:\n\n`Negative Splits` deleted more than you wrote · `Flawless` no errors, no failed tests ·\n`Hill Repeats` climbed out of it 3+ times · `Marathon` 1h+ · `Ultra` 3h+ ·\n`Sprint` under 3 minutes with a diff · `Yak Shave` 30+ tool calls, barely a diff ·\n`All Green` full suite, zero red · `Furnace` 5M+ tokens · `Nocturnal` 11pm–5am ·\n`Everest` 3000m+ · `10K Club` 10 km · `Gran Fondo` 40 km · `Polyglot` 3+ languages ·\n`Red Zone` effort 90+ · `Sightseeing` all reading, no writing ·\n`Signed Off` 10+ edits accepted, none sent back (Cursor only)\n\nMeasured frequency: `Hill Repeats` 47%, `Marathon` 44%, `Yak Shave` 36%,\n`Polyglot` 31%, `10K Club` 25%, `Ultra` 22%, `Flawless` 22%, `Nocturnal` 19%,\n`Red Zone` 14%, `Furnace` 8%, `Everest` 8%. Average 3.1 badges per card.\n\nPersonal records only fire once there is something to beat, so the first activity\nnever claims one.\n\n## Logging every workout\n\nThree modes, in descending cost:\n\n| | per-turn cost | logs sessions | keeps streaks honest |\n|---|---|---|---|\n| **auto** (Stop hook) | ~300 ms | automatically | yes |\n| **manual + day stamp** (default of `--manual`) | ~10 ms | when you ask | yes |\n| **manual only** (`--manual --no-stamp`) | none | when you ask | no |\n\nThe full hook re-parses the transcript and redraws the card every turn. The day\nstamp is a two-line shell script that appends today's date and nothing else — it\nnever starts a Node process, and writes one line per *day*. Streaks count the\nunion of logged-activity days and stamped days, so both modes mean the same thing.\n\nBy hand, any time:\n\n```bash\nnpm run log # the session you are in\nnode scripts/log-now.mjs --cursor # the Cursor conversation you are in\nnode scripts/log-now.mjs --codex # the Codex CLI session you are in\nnode scripts/log-now.mjs --codex --list\nnode scripts/log-now.mjs --list # 15 most recent, newest first\nnode scripts/log-now.mjs 9e22ccfa # one session by id prefix\n```\n\nLogging **upserts** — running it repeatedly on one session updates that activity\ninstead of stacking duplicates. Sessions under 8 tool calls or 2 minutes are\nignored.\n\n### What the Claude Code hook measures\n\n| Field | Source |\n|---|---|\n| Tool calls | `tool_use` blocks in assistant messages |\n| Tokens | `usage` input / output / cache write / cache read, per model |\n| Lines ± | `structuredPatch` hunks from Edit/Write results |\n| Files | Edit/Write paths, **plus** shell redirect / `tee` / `sed -i` targets |\n| Errors recovered | `tool_result.is_error` |\n| Moving time | consecutive timestamp gaps, each capped at 5 min |\n| Model | `message.model`, most frequent in the session |\n\nKnown limits: **cache reads are excluded from the token total** (replayed context\nis not work done); **shell writes are detected by regex**, deliberately\nconservative — it misses writes rather than inventing them, and line counts for\nthose files are not recovered, so churn under-reports on shell-heavy sessions;\n**session type is a guess** from files, churn and error count.\n\n## Backfill: importing past seasons\n\n```bash\nnode scripts/backfill.mjs --dry-run # report only, writes nothing\nnode scripts/backfill.mjs # log everything not yet logged\nnode scripts/backfill.mjs --force # rebuild from empty (backs up first)\nnode scripts/cursor-backfill.mjs # same, for Cursor\nnode scripts/codex-backfill.mjs # same, for Codex CLI\n```\n\nSorted by session time, because personal records are judged against prior history\n— replaying out of order would award them to whichever session happened to be\nprocessed first. Walks `~/.claude/projects/` recursively (git-worktree sessions\nlive several levels deep). Roughly 900 MB of transcripts takes ~25 s including\ncard rendering.\n\n## Cursor\n\nCursor stores chat in SQLite at\n`~/Library/Application Support/Cursor/User/globalStorage/state.vscdb`, one row per\nmessage, keyed `bubbleId: