Agentrava MCP server
Commit Oct 27, 2026Turns coding agent sessions into achievement cards with route maps, climb profiles, and headline statistics based on transcript analysis.
Also known as lukisimi/agentrava
- Stars
- 4
- Tools
- 5
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 27, 2026
- License
- MIT
What is Agentrava MCP?
Agentrava turns coding agent sessions into achievement cards with route maps, climb profiles, and headline statistics based on transcript analysis. It exposes 5 tools, such as agentrava, snapshot, log_activity.
Summary generated from the project's README
About Agentrava MCP server
Transforming coding agent sessions into visual achievement cards is what Agentrava does for developers using AI coding tools. It analyzes session transcripts to generate route maps, climb profiles, and headline statistics that mimic athletic performance metrics. By parsing tool calls, tokens, diff hunks, and recovered errors, the server creates a synthetic record of the agent's work, including badges and personal records.
This MCP server works locally and integrates with clients like Claude Code, Codex CLI, and Cursor. Users can set it up using npx agentrava setup, which registers the server and adds a hook to capture session data automatically. The system uses a specialized parser to ensure that only actual agent work contributes to the climb, excluding environmental errors like permission denials or manual user interruptions.
Developers can generate various visual summaries, including individual session cards, weekly snaps, and monthly recaps. These outputs include metrics such as ground covered, elevation, and tokens burned. The server supports standard stdio communication, making it compatible with any MCP client that follows the protocol.
What you can do with it
- 1Generate a session summary cardAsk your AI client to create a visual recap of your current coding session including a route map and stats.
- 2Create weekly or monthly progress reportsGenerate a summary card covering a specific week or month to track agent activity and costs over time.
- 3Analyze agent efficiency and frictionUse the climb profile and elevation metrics to see where the agent encountered errors or required significant file changes.
- 4Track long-term agent performanceRetrieve career totals, personal records, and trophy cases to see how your agent's activity has evolved.
Written from the project's README. Every use case is checked against a quote from it.
How to install Agentrava MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Agentrava MCP in Claude Code
$ claude mcp add agentrava -- npx -y agentravaInstall Agentrava MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"agentrava": {
"command": "npx",
"args": [
"-y",
"agentrava"
]
}
}
}Install Agentrava MCP in VS Code
.vscode/mcp.json
{
"servers": {
"agentrava": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"agentrava"
]
}
}
}Install Agentrava MCP in VS Code CLI
$ code --add-mcp '{"name":"agentrava","type":"stdio","command":"npx","args":["-y","agentrava"]}'Install Agentrava MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"agentrava": {
"command": "npx",
"args": [
"-y",
"agentrava"
]
}
}
}Install Agentrava MCP in Codex
$ codex mcp add agentrava -- npx -y agentravaInstall Agentrava MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.agentrava] command = "npx" args = ["-y", "agentrava"]
Install Agentrava MCP in Gemini CLI
$ gemini mcp add -s user agentrava npx -- -y agentravaInstall Agentrava MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"agentrava": {
"command": "npx",
"args": [
"-y",
"agentrava"
]
}
}
}Agentrava MCP tools 5
Detected from the READMEagentravasnapshotlog_activityrecapget_profile
| agentrava | — | |
| snapshot | — | |
| log_activity | — | |
| recap | — | |
| get_profile | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablelukisimi/agentrava is public and reachablegithub.com/lukisimi/agentrava ↗Pass
- Package names this repository as its sourceagentrava names lukisimi/agentrava as sourcenpmjs.com/package/agentrava ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-27github.com/lukisimi/agentrava ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from agentravaPass
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model5 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubAgentrava
Your agent worked hard today. It deserves kudos.
Strava, for coding agents. An MCP server that turns a finished session into a bragging card — route map, climb profile, headline stats, badges, personal records.
Part joke, part serious: the numbers are real, the scales are made up.
Nothing on a card is self-reported. A hook parses the session transcript for tool calls, tokens, diff hunks, recovered errors and moving time. The agent never gets to describe its own workout. Works with Claude Code, Codex CLI and Cursor.
Warm-up: install
npx agentrava setup
Copies itself to ~/.agentrava/app, registers the MCP server with Claude Code,
adds the Stop hook, and offers to log your past sessions so the first card you
see is one of your own. If Codex CLI or Cursor is installed, it asks before
touching either. Idempotent, backs up every file it edits, and reversible:
npx agentrava setup --manual # keep the tools, stop logging every turn
npx agentrava setup --auto # put automatic logging back
npx agentrava setup --codex # register with Codex CLI without being asked
npx agentrava setup --yes # accept every offer, ask nothing
npx agentrava setup --uninstall # remove everything (your data is left alone)
npx agentrava@latest setup # update
Restart Claude Code, then ask it to "show my agentrava". Every script below is
also a subcommand — npx agentrava card --best, npx agentrava snap week —
and npx agentrava help lists them.
Why it copies itself: the hook and the server are registered by absolute
path, and npx runs packages from a cache npm can clear at any time. A copy in
~/.agentrava/app keeps working after that. Moving between a clone and the copy
re-points the existing hook instead of adding a second one.
Any other MCP client works — it speaks stdio:
{ "mcpServers": { "agentrava": { "command": "npx", "args": ["-y", "agentrava"] } } }
From a clone, for hacking on it: git clone https://github.com/lukisimi/agentrava && cd agentrava && node scripts/install.mjs.
The setup then registers the clone itself, and the node scripts/… commands in
the rest of this page work as written.
Tools
agentrava— start here: every tool with an example, plus your totals and streak.snapshot— card for the session in progress, measured from the live transcript. Takesphoto("chat"uses an image you just pasted),titleto rename it inline, andshare(full·friends·anonymous) to strip it before you post it.log_activity— log a session by hand; unreported fields count as zero.recap— one card for a whole period: totals, activity heatmap, hour-of-day histogram, trophy case, longest streak, biggest session. Optionalfrom/to.weekly_snap·monthly_snap— a week or a month on one card, same size as a session card. Takeperiod(this,last,last7/last30, or a date),title,hide_projects, andpick.get_profile— career totals, streak, personal records, trophy case.rename_session·rename_project·list_projects— your own names, kept across re-logs.list_activities·leaderboard·set_athlete
The metaphor
| Strava | Agentrava | Formula |
|---|---|---|
| Distance | ground covered | churn / 100 + tool_calls / 25 km |
| Elevation | the parts that hurt | files × 37 + errors × 120 + tests_failed × 45 m |
| Moving time | session time, idle excluded | gaps over 5 min don't count |
| Pace | minutes per km | time / distance |
| Suffer score | Effort, 0–100 | cadence, elevation, tokens, retries |
| Calories | tokens burned | input + cache writes + output |
| Economy | tokens per km | lower is leaner |
| Gear | the model | measured, never assumed |
| — | API cost | priced per message at list rates |
Every weight is fitted to real sessions, not guessed. Churn alone left the median session at 0.00 km — most sessions read and search far more than they write — which is why tool calls carry distance too.
Training science: what the numbers actually mean
The inputs are measured. The scales are invented — 100 lines = 1 km, an error = 120 m — chosen so a median session lands near a plausible 4.4 km. That makes cards comparable between your own sessions, which is what records and the leaderboard rest on, and meaningless outside Agentrava.
Measured across 134 sessions:
| correlates most with | r | |
|---|---|---|
| Distance | tool calls | 0.94 |
| Distance | churn | 0.86 |
| Elevation | errors recovered | 0.91 |
| Elevation | files changed | 0.88 |
So distance is volume of activity — 69% of it from the tool-call term — and elevation is friction, 58% of it from errors. They correlate 0.79 with each other: overlapping, but about a third of elevation is information distance doesn't carry, which is what separates a long easy session from a short brutal one.
Not every failed tool call is friction
An error is a tool result the client flagged as failed. Sampled across 166 real Claude Code errors: 45% a shell command exiting non-zero, 11% bad arguments or a missing file, 7% a browser step, 19% app-level errors from the user's own tools — and 12% nothing to do with the agent at all: the human declining a tool call, the permission layer blocking one, a model or MCP server briefly unavailable.
Those last ones are counted separately (errors_environmental) and left out of
the climb, because 120 m of elevation and a loop in the route should mean work
that had to be redone, not a moment where someone hit Escape. Across this store
that removed 89 errors and 8 km of climb, and demoted 4 cards from Debug.
The test, in src/errors.js, is a phrase list run against the
first 300 characters of the failure text — these failures announce themselves
in their first line, while a long command output can mention "rate limit"
anywhere. 609 successful Cursor tool results contain that phrase and not one of
them is a rate limit. Deliberately excluded from the list: permission denied
(a real filesystem failure the agent must work around), a bare timed out
(usually its own command hanging) and connection refused (usually a dev server
it forgot to start).
Each client hides the text somewhere different — Claude Code in the
tool_result, Cursor in toolFormerData.result, Codex in a failed item's
result for an MCP call or stderr for a shell one. Serialising a whole Codex
item instead tested the command line and the id, which counted a session that
merely printed the word "rejected" as a refusal.
Errors are not a measure of inefficiency. Their raw count is mostly a size measurement — 0.87 against tool calls. As a rate (errors per 100 tool calls) they correlate 0.08 with tokens per line changed and −0.01 with seconds per line changed. Across 78 sessions, a 5× difference in error rate bought 20% more tokens per line and 18% less time per line: no signal. Elevation honestly means eventful, not wasteful.
Raw tokens cannot rank efficiency. They correlate 0.72 with distance, so the number mostly says how big a session was. Economy (tokens per km) correlates 0.08 with distance — size-independent, and therefore actually comparable. It measures token cost per unit of volume, not of value: a session that finds the right answer in five calls scores badly on it.
None of this measures whether the work was any good. A session that flails for 800 tool calls outscores one that fixes the bug in five. Nothing in a transcript reliably encodes outcome — that's a ceiling, not a tuning problem.
The route and the climb profile
The route map is a random walk seeded by the activity id, so a card always redraws identically. Two things in it are real: its length and density come from tool calls, and every error you recovered from draws as a loop — the trace shows where you went in circles.
The climb profile under it is cumulative elevation: flat where the session ran smoothly, stepping up wherever a file was written or an error recovered, bucketed by moving time so an idle gap doesn't collapse it. The area under the curve is the elevation figure on the card.
That strip was decoration until recently — a seeded random walk reading no session data at all, the same label over pure noise. Sessions with fewer than three climb events now get no strip at all rather than an invented one. 81% have a profile.
Weekly and Monthly Snap
node scripts/snap.mjs week # this calendar week so far
node scripts/snap.mjs week last # the previous calendar week
node scripts/snap.mjs week last7 # rolling seven days, ending today
node scripts/snap.mjs month # this calendar month so far
node scripts/snap.mjs month last30 # rolling thirty days (14d, 90d… also work)
node scripts/snap.mjs month 2026-08 --pick 086f7bf6 # feature a session you chose
node scripts/snap.mjs week --title "Shipped the new onboarding" --hide-projects
Calendar or rolling. A calendar week shared on a Wednesday is a stub — it
says "this week so far" and two days are empty. last7 and last30 are always
whole windows ending today, which is usually what you want to post. Calendar
periods stay the default because streaks, months and heatmaps are calendar
things. Rolling cards label themselves by range and by weekday, since a rolling
week does not start on a Monday.
Both are 1080×1350, the same frame as a session card, so a snap and a card sit side by side in a feed. A six-row month is the tightest case and still clears the footer.
Weekly — agent time per day, sessions / active days / projects, tool calls, estimated cost, and the longest session. Monthly — a Monday-first heatmap, the same headline counts, the top three projects by time, and a featured session.
What makes the numbers hold together:
- Daily buckets are recorded, not inferred. Both parsers credit each stretch of moving time to the local day it happened, splitting at midnight, so a session from 23:50 to 00:05 counts 10 minutes on one day and 5 on the next. Every bar and heatmap cell comes from those buckets, and so does Active Days — seven bars can't sit next to a five-day headline.
- A session crossing a period boundary appears in both, with its time apportioned. Tool calls and cost have no per-day record, so they are apportioned by the same time share.
- "Agent time" is summed across sessions. Nine agents running in parallel for five hours is 45 hours of agent time on one day. The card says so under the chart; it is not your working hours.
- Cost says when it is partial —
partial · 38 of 40 priced— and reads "not recorded" rather than $0 when nothing could be priced. - "Month's pick · Selected by you" appears only when you picked it. Otherwise the feature is labelled "Longest session", which is what it is.
- An unfinished period says so — "This week so far".
- Nothing is inferred about outcome. A
--titleis yours to write; the card never claims anything shipped.
Badges
Earnable, not participation trophies:
Negative Splits deleted more than you wrote · Flawless no errors, no failed tests ·
Hill Repeats climbed out of it 3+ times · Marathon 1h+ · Ultra 3h+ ·
Sprint under 3 minutes with a diff · Yak Shave 30+ tool calls, barely a diff ·
All Green full suite, zero red · Furnace 5M+ tokens · Nocturnal 11pm–5am ·
Everest 3000m+ · 10K Club 10 km · Gran Fondo 40 km · Polyglot 3+ languages ·
Red Zone effort 90+ · Sightseeing all reading, no writing ·
Signed Off 10+ edits accepted, none sent back (Cursor only)
Measured frequency: Hill Repeats 47%, Marathon 44%, Yak Shave 36%,
Polyglot 31%, 10K Club 25%, Ultra 22%, Flawless 22%, Nocturnal 19%,
Red Zone 14%, Furnace 8%, Everest 8%. Average 3.1 badges per card.
Personal records only fire once there is something to beat, so the first activity never claims one.
Logging every workout
Three modes, in descending cost:
| per-turn cost | logs sessions | keeps streaks honest | |
|---|---|---|---|
| auto (Stop hook) | ~300 ms | automatically | yes |
manual + day stamp (default of --manual) |
~10 ms | when you ask | yes |
manual only (--manual --no-stamp) |
none | when you ask | no |
The full hook re-parses the transcript and redraws the card every turn. The day stamp is a two-line shell script that appends today's date and nothing else — it never starts a Node process, and writes one line per day. Streaks count the union of logged-activity days and stamped days, so both modes mean the same thing.
By hand, any time:
npm run log # the session you are in
node scripts/log-now.mjs --cursor # the Cursor conversation you are in
node scripts/log-now.mjs --codex # the Codex CLI session you are in
node scripts/log-now.mjs --codex --list
node scripts/log-now.mjs --list # 15 most recent, newest first
node scripts/log-now.mjs 9e22ccfa # one session by id prefix
Logging upserts — running it repeatedly on one session updates that activity instead of stacking duplicates. Sessions under 8 tool calls or 2 minutes are ignored.
What the Claude Code hook measures
| Field | Source |
|---|---|
| Tool calls | tool_use blocks in assistant messages |
| Tokens | usage input / output / cache write / cache read, per model |
| Lines ± | structuredPatch hunks from Edit/Write results |
| Files | Edit/Write paths, plus shell redirect / tee / sed -i targets |
| Errors recovered | tool_result.is_error |
| Moving time | consecutive timestamp gaps, each capped at 5 min |
| Model | message.model, most frequent in the session |
Known limits: cache reads are excluded from the token total (replayed context is not work done); shell writes are detected by regex, deliberately conservative — it misses writes rather than inventing them, and line counts for those files are not recovered, so churn under-reports on shell-heavy sessions; session type is a guess from files, churn and error count.
Backfill: importing past seasons
node scripts/backfill.mjs --dry-run # report only, writes nothing
node scripts/backfill.mjs # log everything not yet logged
node scripts/backfill.mjs --force # rebuild from empty (backs up first)
node scripts/cursor-backfill.mjs # same, for Cursor
node scripts/codex-backfill.mjs # same, for Codex CLI
Sorted by session time, because personal records are judged against prior history
— replaying out of order would award them to whichever session happened to be
processed first. Walks ~/.claude/projects/ recursively (git-worktree sessions
live several levels deep). Roughly 900 MB of transcripts takes ~25 s including
card rendering.
Cursor
Cursor stores chat in SQLite at
~/Library/Application Support/Cursor/User/globalStorage/state.vscdb, one row per
message, keyed bubbleId:<conversationId>:<bubbleId>.
The database is WAL-mode, and while Cursor runs it usually has megabytes of
uncommitted log. Opening it with immutable=1 makes SQLite ignore the WAL — which
hides the newest conversations entirely and throws "malformed" when a checkpoint
lands mid-read. Reads use mode=ro, falling back to a snapshot of the db plus its
-wal and -shm. The whole database is read in one grouped pass (~60 s for
289 conversations); per-conversation LIKE queries each scan a multi-GB table.
What Cursor actually records
Measured across 222 logged conversations:
| signal | coverage | |
|---|---|---|
| tool calls | 100% | ✅ |
| moving time | 100% | ✅ |
| climb profile | 89% | ✅ |
| errors | 57% | ✅ a real status field, cleaner than Claude Code's boolean |
userDecision |
40% | ✅ accepted / rejected per edit — no equivalent in Claude Code |
| tokens | 4% | ❌ tokenCount unpopulated since Jan 2026 |
| files changed | 6% | ❌ see below |
| line churn | 0% | ❌ see below |
Cursor stores arguments for only 477 of 15,142 edit_file_v2 calls; the rest
have empty rawArgs, and the result holds content hashes rather than paths. So
which file an edit touched is usually unrecoverable, and files_changed
counts only the subset that is.
This was worse before: the parser took a path from any tool carrying one,
including read_file_v2, so files merely opened counted as changed and inflated
elevation (median Cursor elevation 555 m → 120 m once restricted to real edits).
Under-reporting something unmeasurable beats inflating it, so Cursor elevation
rests mainly on errors — which it does record reliably.
Cursor has a stop hook with the same stdio-JSON contract as Claude Code
(conversation_id, transcript_path, workspace_roots, status), and
hooks/cursor-probe.mjs captures one real payload. Live auto-logging is not
wired up: a full scan takes ~60 s, too slow for every turn.
Codex CLI
Codex writes one JSONL rollout per session under
~/.codex/sessions/YYYY/MM/DD/rollout-<timestamp>-<uuid>.jsonl, with a timestamp
on every line, so moving time, daily buckets and the climb profile come out the
same way they do for Claude Code. 130 rollouts totalling 330 MB parse in about
two seconds; the largest single file, 119 MB, takes 566 ms.
It records file changes better than the other two clients. An item_completed
event of type FileChange carries a changes map: the full body for an added
file, a unified diff for an edited one. Churn is counted from those diffs rather
than inferred from shell commands (Claude Code) or given up on (Cursor).
Measured across the 24 sessions above the logging floor:
| signal | coverage | |
|---|---|---|
| tool calls | 100% | ✅ custom_tool_call, function_call, tool_search_call |
| moving time | 100% | ✅ |
| tokens in/out/cached | 100% | ✅ token_count.info.total_token_usage |
| files and line churn | 100% of sessions that changed a file | ✅ exact, from FileChange diffs |
| errors | 54% | ✅ item_completed with status: "failed" |
| model | 100% | ✅ from turn_context |
| est. API cost | 100% | ✅ OpenAI list prices, per model and tier |
| accepted / rejected edits | 0% | ❌ not recorded |
Token totals are cumulative in the log, so the last token_count wins rather
than being summed, and input_tokens includes the cached portion — the cached
tokens are subtracted back out so a Codex card's token count means what a Claude
Code card's does.
Pricing a Codex session takes two passes. The cumulative totals say how many
tokens there were; the per-request last_token_usage figures say which model and
which price tier they ran under. Summing the per-request figures instead would
overstate a session that replays part of its own history — one rollout in four
came out 5% high — so the totals stay authoritative and the per-request numbers
decide only how the tokens divide.
OpenAI charges a whole request at 2× input and 1.5× output once its prompt passes 272K input tokens. Across 3,329 requests here the largest prompt was 245K, and Codex ran a 258K context window, so the higher tier never applied — but it is implemented rather than assumed away.
Codex's own codex-auto-review model has no published rate. Its turns price at
zero rather than being guessed at, exactly as an unrecognised Claude model does.
Two things in the log are not what they look like:
- The first user message is not the prompt. Codex opens a session by feeding
itself the environment block,
AGENTS.md, the plugin list and a replayed approval history as user messages. Taken verbatim, sessions were titled<recommended_plugins>. Those are skipped. - Each Codex conversation gets its own directory when Codex runs from the
ChatGPT app:
<workspace>/Codex/<date>/<conversation-slug>. One project per session, each named after the conversation — which would put chat titles on a card meant to be shared. They group under the Codex workspace instead. A Codex session started inside a real repository still reports that repository.
Of 130 rollouts, 105 fall below the 8-tool-call floor: most are chat-only threads with no tools at all, which the same floor would reject in any client.
There is no auto-logging hook. Codex's notify takes a single program and is
usually already claimed by something else, so taking it over would break whatever
was there. Log from Codex with the snapshot MCP tool (npx agentrava setup --codex
registers the server in ~/.codex/config.toml) or with
node scripts/log-now.mjs --codex.
Cards
Athlete and gear
The athlete is you, not the model — Strava does not file your rides under the
bike. The model is gear, shown under the title with the client:
Claude Opus 5 · Cursor.
node scripts/whoami.mjs "Your Name" # the name on every card, past and future
node scripts/whoami.mjs --avatar ~/me.jpg # a picture for the circle
node scripts/whoami.mjs --avatar chat # use an image you just pasted into the chat
node scripts/whoami.mjs --no-avatar # back to the initial
node scripts/whoami.mjs # show both
The avatar replaces the initial in the circle on every card and snap, clipped to
the circle. It is copied into ~/.agentrava/avatars/ on set, so moving or
deleting the original does not blank your cards, and it is swappable any time —
setting a new one redraws everything. set_athlete takes avatar and
avatar_reset for the same thing from chat.
set_athlete does the same from chat. Unset, cards read "Athlete" — the safe
default for sharing.
Agentrava MCP questions
How do I add Agentrava MCP to Claude Code?
Run claude mcp add agentrava -- npx -y agentrava in your terminal. Add --scope user to make it available in every project.
How do I add Agentrava MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Agentrava MCP provide?
It exposes 5 tools, including agentrava, snapshot, log_activity, recap, get_profile.
How are the session statistics measured?
Statistics are parsed directly from the session transcript, including tool calls, tokens, diff hunks, and recovered errors, rather than being self-reported by the agent.
Which coding agents or clients are supported?
The server works with Claude Code, Codex CLI, and Cursor.
Can I uninstall Agentrava?
Yes, you can remove everything using the uninstall command, and your data will be left alone.
Does it work with other MCP clients?
Yes, any other MCP client that speaks stdio can use it.