AgentPlayerAchievements

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

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.

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

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

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

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

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

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

Quick start with any MCP client:

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

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