AgentPlayerAchievements

MCP-powered local platform turns vibe coding into a game. Steam-style achievements for Claude Code, Hermes and more.

Gamified achievement system for AI coding agents.
Earn XP, unlock trophies, level up — just by doing what you already do.

Claude Code·Kilo Code·OpenCode·Hermes·OpenClaw

Quick Start·How It Works·Features·Supported Tools·CLI Commands·Community Packs·Dashboard·Security & Privacy·Contributing·FAQ

# Option A: install globally (recommended for users) npm install -g @eiainano/agpa agpa init # Option B: clone and link (recommended for contributors) git clone https://github.com/eiainano/AgentPlayerAchievements.git cd AgentPlayerAchievements && npm install && npm link agpa init

[!TIP] Want to see what the dashboard looks like without waiting for real unlocks? Runagpa demoto generate sample data instantly.

agpa dashboard # open the achievement dashboard agpa stats # check your progress agpa assets download # (optional) pre-download all 219 pixel-art badges

Your Coding Session │ ├─ You code, agent responds — every action is tracked │ └─ dual-channel: MCP tools + Hook events │ ├─ Session ends → engine evaluates 217 achievements │ └─ unlocked? → macOS notification 🎉 │ └─ agpa dashboard → view, sort, filter, share

Two data channels → one engine → one dashboard:

Both channels write to the same~/.agent-achievements/event log. The engine evaluates 12 condition types against 217 achievements.

[!NOTE]Zero overhead.The Hook CLI is a sub-millisecond subprocess. The MCP server runs on STDIO with no network calls. All data stays on your machine.

- 🎮Achievement Dashboard— XP bar, level, streak, activity heatmap, rarity breakdown, showcase
- 🏆217 Achievementsacross 11 categories — from "Hello World" to "Completionist"
- 🔥GitHub-style activity heatmap— 4 months of coding activity at a glance
- 📸Share Card— dark/light themed, bilingual, downloadable PNG
- 🔊8-bit sound effects & notifications— rarity-graded retro sounds + desktop push notifications on unlock
- 📂Multi-profile— up to 4 profiles, switch anytime (work, personal, experimentation)

All five tools have full dual-channel coverage except Hermes (no hook API). For any MCP-compatible client (Cursor, VS Code, Windsurf, etc.), MCP-only tracking works out of the box — you just miss hook-based auto-tracking.

[!TIP]New to MCP?Start withagpa init— it auto-detects your installed tools and configures everything. Manual JSON configs below are fallbacks.

agpa initauto-detects Claude Code and registers both channels. For manual setup:

MCP config(~/.claude/.mcp.jsonor project-root.mcp.json):

{ "mcpServers": { "agpa": { "command": "npx", "args": ["-y", "@eiainano/agpa", "agpa-mcp"] } } }

Hook registration—agpa initadds hook entries to your Claude Code settings. Verify withagpa verify.

These editors support MCP but don't expose hook APIs for auto-tracking. You get tool-call tracking via MCP.

{ "mcpServers": { "agpa": { "command": "npx", "args": ["-y", "@eiainano/agpa", "agpa-mcp"] } } }

{ "mcpServers": { "agpa": { "command": "npx", "args": ["-y", "@eiainano/agpa", "agpa-mcp"] } } }

These tools support TS plugins for hook-level auto-tracking.agpa initregisters the plugin + MCP config.

Manual MCP config(opencode.jsonor Kilo Code settings):

{ "mcpServers": { "agpa": { "command": "npx", "args": ["-y", "@eiainano/agpa", "agpa-mcp"] } } }

The TS plugin (registered byagpa init) handles PostToolUse, SessionStart, SessionEnd, and other hook events automatically.

Hermes does not expose a hook API. MCP-based tracking covers tool calls and session events.

{ "mcpServers": { "agpa": { "command": "npx", "args": ["-y", "@eiainano/agpa", "agpa-mcp"] } } }

OpenClaw supports a plugin system for hook-level tracking.agpa initregisters both the plugin and MCP config.

{ "mcpServers": { "agpa": { "command": "npx", "args": ["-y", "@eiainano/agpa", "agpa-mcp"] } } }

AGPA runs aModel Context Protocolserver (stdio transport) that exposes 7 tools for any MCP-compatible client — Claude Desktop, Cursor, VS Code, Windsurf, and more.

{ "mcpServers": { "agpa": { "command": "npx", "args": ["-y", "@eiainano/agpa", "agpa-mcp"] } } }

Already installed AGPA globally? Runagpa-mcpdirectly. The server auto-detects your active profile and tool source.

Anyone can create and share achievement packs. Drop a YAML file into~/.agent-achievements/packs/to install:

agpa pack list # list installed packs agpa pack info <id> # show pack details

SeeCreating Achievement Packsfor the pack format spec, event type catalog, and 12 condition types.

agpa dashboard # default :3867 agpa dashboard 8080 # custom port agpa dashboard --profile work # launch with specific profile

┌─────────────────────────┐ │ Engine (src/engine/) │ │ track() / poll() │ └─────────────────────────┘ ↗ ↖ MCP Server Hook CLI (src/main.ts) (src/cli/hook.ts) │ │ STDIO long-lived short-lived subprocess │ (stdin pipe) │ │ Agent calls Hooks fire consciously automatically │ │ ┌─────┴─────┐ ┌──────┴──────┐ │ Manual │ │ Auto-track │ │ image.read │ │ tool.complete│ │ lang_used │ │ file.edit │ │ plan.mode │ │ session. │ │ ... │ │ agent.spawn │ └───────────┘ └─────────────┘ ╲ ╱ event.log ← both write here │ engine.poll() │ state.json │ Dashboard

src/ ├── main.ts # MCP Server entry (STDIO) ├── tool-registry.ts # Central tool registration ├── cli/ │ ├── index.ts # Unified CLI entry (27 commands) │ ├── hook.ts # Hook CLI (track + poll + auto modes) │ ├── init.ts # Interactive install wizard │ ├── dashboard.ts # Dashboard launcher │ ├── doctor.ts # System diagnostic │ └── ... # 22 more CLI commands ├── engine/ │ ├── engine.ts # Core engine (track / poll / stats) │ ├── evaluator.ts # 12 condition type evaluators │ ├── store.ts # JSONL event log + state persistence │ ├── types.ts # TypeScript interfaces │ └── yaml-parser.ts # YAML achievement definition parser ├── dashboard/ │ ├── server.ts # HTTP server + API routes │ ├── api.ts # Card data, stats aggregation │ ├── public/ # Zero-framework HTML/CSS/JS frontend │ └── customize-api.ts # Self-customize endpoint ├── tools/ # MCP tool definitions (7 tools) ├── utils/ # notify, validate, profile, pixel-art, battery, etc. ├── verify/ │ └── auditor.ts # Achievement verification logic ├── config.ts # Global configuration └── helpers.ts # Shared utilities pixel-art-output/ # Logo images (README) achievement-definitions.yaml # 217 achievement definitions (authoritative) scripts/ # dev tools (logo gen, pixel art gen, sounds)

Q: How is this different from WakaTime or coding activity trackers?A: WakaTime tells youwhatyou did — hours, languages, projects. AGPA makes itfun*— XP, levels, achievements, streaks, and Steam-style dopamine hits. It's gamification layered on top of your existing workflow, not another dashboard to check. Think of it as the difference between a fitness tracker's raw step count and a Pokémon Go badge — same data, different experience.

Q: Can I customize achievement names?A: Yes./customizepage in the dashboard lets you rename any achievement.

[!IMPORTANT]First step for any issue:Runagpa doctor— it diagnoses tracking status, hook registration, event coverage, and configuration problems in one shot.

For persistent issues, check~/.agent-achievements/error.logoropen an issue.

Perform queries and entity operations in your Fibery workspace.