# Agent Player Achievements (AGPA) 🏆

EN | 中文 | ES | 한국어 | 日本語

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

--- ### Without AGPA ❌ - **No visibility** into your coding habits across sessions - **Can't track progress** — getting faster? Using more tools? No way to know - **No motivation** to explore your agent's full feature set - **Same routine** every day — no surprises, no milestones ### With AGPA ✅ - **Auto-tracking** — every tool call, file edit, and git commit logged automatically - **Steam-style dashboard** — XP bar, levels, streaks, heatmaps, achievement showcase - **217 achievements** across 11 categories — from "Hello World" to "Completionist" - **Instant feedback** — terminal popups, macOS notifications, 8-bit sounds on unlock --- ## Dashboard Preview

AGPA Home
_{Home — XP bar, streaks, agent stats} Achievement Grid
_{Achievements — 217 achievements × 11 categories}

Achievement Sets
_{Sets — themed collections with progress tracking} Achievement Detail
_{Detail Card — rarity, unlock date, replay animation}

--- ## Quick Start **Prerequisites:** Node.js ≥ 18 ```bash # 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 ``` That's it. Keep using your agent — achievements unlock automatically as you work. > [!TIP] > Want to see what the dashboard looks like without waiting for real unlocks? Run `agpa demo` to generate sample data instantly. ```bash agpa dashboard # open the achievement dashboard agpa stats # check your progress agpa assets download # (optional) pre-download all 219 pixel-art badges ``` ## How It Works ``` 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:** | Channel | Method | Captures | |---------|--------|----------| | **Hook CLI** | Tool hooks (subprocess via stdin) | file.read/write/edit, tool.complete, git.commit, session.start/end, task.complete, agent.spawn | | **MCP Server** | STDIO protocol (7 tools) | image.read, file.language_used, plan.mode_entered, user.message, automode.start, achievement config, explain | 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. ## Features - 🎮 **Achievement Dashboard** — XP bar, level, streak, activity heatmap, rarity breakdown, showcase - 🏆 **217 Achievements** across 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) ## Supported Tools

| Tool | Auto-track | MCP track | Easiest Setup | |------|:----------:|:---------:|---------------| | Claude Code | ✅ | ✅ | `agpa init` auto-detects | | Kilo Code | ✅ | ✅ | TS plugin + MCP config | | OpenCode | ✅ | ✅ | TS plugin + MCP config | | Hermes | — | ✅ | MCP JSON config | | OpenClaw | ✅ | ✅ | Plugin + MCP config | 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 with `agpa init` — it auto-detects your installed tools and configures everything. Manual JSON configs below are fallbacks.

Claude Code — auto-track + MCP (full coverage)

`agpa init` auto-detects Claude Code and registers both channels. For manual setup: **MCP config** (`~/.claude/.mcp.json` or project-root `.mcp.json`): ```json { "mcpServers": { "agpa": { "command": "npx", "args": ["-y", "@eiainano/agpa", "agpa-mcp"] } } } ``` **Hook registration** — `agpa init` adds hook entries to your Claude Code settings. Verify with `agpa verify`.

Cursor / VS Code — MCP only

These editors support MCP but don't expose hook APIs for auto-tracking. You get tool-call tracking via MCP. **Cursor** (`.cursor/mcp.json`): ```json { "mcpServers": { "agpa": { "command": "npx", "args": ["-y", "@eiainano/agpa", "agpa-mcp"] } } } ``` **VS Code** (`.vscode/mcp.json`): ```json { "mcpServers": { "agpa": { "command": "npx", "args": ["-y", "@eiainano/agpa", "agpa-mcp"] } } } ```

Kilo Code / OpenCode — auto-track + MCP (full coverage)

These tools support TS plugins for hook-level auto-tracking. `agpa init` registers the plugin + MCP config. **Manual MCP config** (`opencode.json` or Kilo Code settings): ```json { "mcpServers": { "agpa": { "command": "npx", "args": ["-y", "@eiainano/agpa", "agpa-mcp"] } } } ``` The TS plugin (registered by `agpa init`) handles PostToolUse, SessionStart, SessionEnd, and other hook events automatically.

Hermes — MCP only

Hermes does not expose a hook API. MCP-based tracking covers tool calls and session events. **MCP config** (`~/.hermes/mcp.json`): ```json { "mcpServers": { "agpa": { "command": "npx", "args": ["-y", "@eiainano/agpa", "agpa-mcp"] } } } ```

OpenClaw — auto-track + MCP (full coverage)

OpenClaw supports a plugin system for hook-level tracking. `agpa init` registers both the plugin and MCP config. **Manual MCP config**: ```json { "mcpServers": { "agpa": { "command": "npx", "args": ["-y", "@eiainano/agpa", "agpa-mcp"] } } } ```

## MCP Server AGPA runs a [Model Context Protocol](https://modelcontextprotocol.io) server (stdio transport) that exposes 7 tools for any MCP-compatible client — Claude Desktop, Cursor, VS Code, Windsurf, and more. | Tool | Description | |------|-------------| | `achievement.track` | Record an agent event (lightweight, <1ms append-only write) | | `achievement.poll` | Evaluate pending events → check for unlocks → return new achievements | | `achievement.stats` | Get player stats: XP, level, total achievements, streaks, recent activity | | `achievement.showcase` | Display all achievement definitions — name, category, rarity, progress | | `achievement.config` | Read/write AGPA config: language, notification preferences, profile | | `achievement.suggest` | Get personalized achievement recommendations based on current progress | | `achievement.explain` | Explain why an achievement is (un)locked — condition breakdown with event history | **Quick start with any MCP client:** ```json { "mcpServers": { "agpa": { "command": "npx", "args": ["-y", "@eiainano/agpa", "agpa-mcp"] } } } ``` > Already installed AGPA globally? Run `agpa-mcp` directly. The server auto-detects your active profile and tool source. ## CLI Commands | Command | Description | |---------|-------------| | `agpa init` | Auto-detect and register with your agent tools | | `agpa uninstall` | Cleanly remove AGPA from all configured tools | | `agpa verify` | Check installation correctness | | `agpa doctor` | Diagnose system state | | `agpa dashboard` | Start achievement dashboard (localhost:3867) | | `agpa stats` | Show achievement progress summary | | `agpa progress` | List all achievements with unlock status | | `agpa profile` | Manage achievement profiles (create, list, switch, softwares, delete) | | `agpa demo` | Generate MVP demo data for testing | | `agpa reset` | Reset all tracking data | | `agpa config` | View/modify config (lang, sound, debug...) | | `agpa showcase` | Manage showcase (list, pin, unpin, auto-fill) | | `agpa search` | Search achievements by keyword/rarity/category | | `agpa suggest` | Suggest next achievement to hunt | | `agpa sound` | Toggle 8-bit rarity-graded sound effects (on, off) | | `agpa activity` | View streak + 4-month activity heatmap | | `agpa export` | Export achievement data as JSON | | `agpa import` | Import from backup | | `agpa mcp` | Start MCP server (stdio mode) | | `agpa web` | Alias for `agpa dashboard` | | `agpa pack` | List or inspect installed community achievement packs | | `agpa banner` | Switch terminal banner color theme (Neon/Arcade/Gold) | | `agpa history` | Browse raw event log entries | | `agpa explain` | Show why an achievement is locked/unlocked (condition breakdown) | | `agpa watch` | Real-time achievement progress monitor | | `agpa upgrade` | Check for updates and upgrade AGPA | | `agpa completion` | Generate shell completion script (bash/zsh/fish) | > Full CLI reference: `agpa --help` ## Community Packs Anyone can create and share achievement packs. Drop a YAML file into `~/.agent-achievements/packs/` to install: ```bash agpa pack list # list installed packs agpa pack info # show pack details ``` See [Creating Achievement Packs](docs/creating-achievements.md) for the pack format spec, event type catalog, and 12 condition types. ## Dashboard

Stats row → Streak + Heatmap → Showcase → Achievement grid with search/filter

```bash agpa dashboard # default :3867 agpa dashboard 8080 # custom port agpa dashboard --profile work # launch with specific profile ``` - **Stats**: XP, level, total achievements, streak, tasks, tool uses - **Heatmap**: GitHub-style 4-month activity grid - **Showcase**: Pinned favorite achievements (up to 6) - **Achievement Grid**: search, sort by rarity/category, filter unlocked/locked - **Sound toggle**: 8-bit rarity-graded effects - **Share button**: generates a beautiful bilingual card → PNG download ## Architecture ``` ┌─────────────────────────┐ │ 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 ``` ## Project Structure ``` 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) ``` ## 🔒 Security & Privacy - **Local-first** — All event data stays in `~/.agent-achievements/`. No telemetry, no cloud sync, no network calls at runtime. - **Auditable** — The engine is pure TypeScript functions operating on JSONL files. No obfuscation, no binary blobs. - **Minimal dependencies** — 5 runtime dependencies (`@modelcontextprotocol/sdk`, `yaml`, `zod`, `figlet`, `tsx`) — all widely audited. - **STDIO isolation** — The MCP server communicates via standard I/O only. No HTTP endpoints exposed. - **Hook sandbox** — The Hook CLI runs as a sub-millisecond subprocess — it cannot persist state or access the network. - **Supply chain** — No native modules, no postinstall scripts, no binary downloads at install time. To report a vulnerability, see [SECURITY.md](SECURITY.md). ## 👥 Contributing We welcome contributions! Whether it's an achievement pack, a Dashboard improvement, a new tool integration, or an engine fix — there's a path for every skill level. - **[CONTRIBUTING.md](CONTRIBUTING.md)** — setup, coding conventions, PR process, and 4 contribution paths - **[Creating Achievement Packs](docs/creating-achievements.md)** — the complete guide to writing achievement definitions - **[`.github/ISSUE_TEMPLATE/`](.github/ISSUE_TEMPLATE/)** — issue and PR templates ## 🌐 Environment Variables | Variable | Description | Default | Values | |----------|-------------|---------|--------| | `AGPA_PROFILE` | Active profile name | `default` | any string | | `AGPA_LANG` | Interface language | `en` | `en`, `zh` | | `AGPA_ENABLED_CATEGORIES` | Filter which achievement categories are active | all | comma-separated (e.g. `onboarding,tool_mastery`) | | `AGPA_DEBUG` | Enable verbose debug logging | `false` | `true` | | `AGPA_SOUND` | Override sound effects | config setting | `on`, `off`, `true`, `false` | | `AGPA_SIMPLE_ANIMATIONS` | Use simplified terminal animations | `false` | `true` | | `AGPA_BANNER_THEME` | CLI startup banner style | `Arcade` | `Neon`, `Arcade`, `Gold` | | `AGPA_TELEMETRY` | Enable anonymous usage telemetry | `false` | `true`, `false` | | `AGPA_TELEMETRY_SERVER` | Custom telemetry endpoint URL | `''` (none) | URL string | | `AGPA_TOOL_SOURCE` | Override tool source identifier | auto-detected | `claude-code`, `hermes`, `openclaw`, etc. | | `AGPA_MODEL` | Current AI model name (for achievements) | `auto` | any model string | > [!TIP] > Environment variables override `config.json` settings. Set them in your shell profile or agent configuration for persistent overrides. ## FAQ **Q: Does this slow down my agent?** A: No. The Hook CLI is a sub-millisecond subprocess. The MCP server runs on STDIO with zero network overhead. **Q: Can I use it with multiple agents?** A: Yes. The init wizard auto-detects Claude Code, Kilo Code, OpenCode, Hermes, and OpenClaw. Each can have its own profile. **Q: My achievements aren't unlocking?** A: Run `agpa doctor` — it diagnoses tracking status, hook registration, and event coverage. **Q: How is this different from WakaTime or coding activity trackers?** A: WakaTime tells you *what* you did — hours, languages, projects. AGPA makes it *fun* — 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. `/customize` page in the dashboard lets you rename any achievement. ## Troubleshooting > [!IMPORTANT] > **First step for any issue:** Run `agpa doctor` — it diagnoses tracking status, hook registration, event coverage, and configuration problems in one shot. | Symptom | Likely Cause | Fix | |---------|-------------|-----| | Achievements not unlocking | Hook/MCP not registered | Run `agpa doctor` to check hook registration + event coverage | | Dashboard won't start | Port 3867 already in use | `agpa dashboard 8080` (or any free port) | | `agpa init` fails | Agent tool not detected | Check supported tools list; use manual MCP JSON config as fallback | | No macOS notifications | `terminal-notifier` missing | Run `brew install terminal-notifier`, or `agpa init` auto-installs it | | Sound not playing | Audio context blocked by browser | Click anywhere on the dashboard page to enable audio | | Profile switching not working | Profile doesn't exist | `agpa profile list` to see available profiles, then `agpa profile switch ` | | Hook CLI errors in agent logs | stdin pipe is empty (expected for first run) | Normal — hooks are short-lived subprocesses; errors are logged to `~/.agent-achievements/error.log` | For persistent issues, check `~/.agent-achievements/error.log` or [open an issue](https://github.com/eiainano/AgentPlayerAchievements/issues). ## Star History

## License MIT — see [LICENSE](LICENSE)

_{Home — XP bar, streaks, agent stats}	_{Achievements — 217 achievements × 11 categories}
_{Sets — themed collections with progress tracking}	_{Detail Card — rarity, unlock date, replay animation}