Agent Player Achievements (AGPA) 🏆

EN |  |  |  | 

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

·

·

·

·

·

·

·

·

·

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

Home — XP bar, streaks, agent stats

Achievements — 217 achievements × 11 categories

Sets — themed collections with progress tracking

Detail Card — rarity, unlock date, replay animation

Quick Start

Prerequisites: Node.js ≥ 18

# 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.

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:

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

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`):

{
  "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`):

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

VS Code (`.vscode/mcp.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):

{
  "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`):

{
  "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:

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

MCP Server

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

CLI Commands

> Full CLI reference: `agpa --help`

Community Packs

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          # show pack details

See Creating Achievement Packs for the pack format spec, event type catalog, and 12 condition types.

Dashboard

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

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.

👥 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** — setup, coding conventions, PR process, and 4 contribution paths
• **Creating Achievement Packs** — the complete guide to writing achievement definitions
• **`.github/ISSUE_TEMPLATE/`** — issue and PR templates

🌐 Environment Variables

> [!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.

For persistent issues, check `~/.agent-achievements/error.log` or open an issue.

Star History

License

MIT — see LICENSE