# Agent Player Achievements (AGPA) 🏆

AIコーディングエージェントのためのゲーミフィケーション実績システム。
XPを獲得し、トロフィーを解除し、レベルアップ — いつもの作業をしながら。

Claude Code · Kilo Code · OpenCode · Hermes · OpenClaw

クイックスタート · 仕組み · 機能 · 対応ツール · CLIコマンド · コミュニティパック · ダッシュボード · セキュリティ · コントリビューション · FAQ

--- ## ダッシュボードプレビュー

AGPA ホーム
_{ホーム — XPバー、連続記録、エージェント統計}
_{成就 — 217個の実績 × 11カテゴリ}

セット
_{套装 — テーマコレクション × 進捗}
_{詳細カード — レア度、解除日、リプレイ}

--- ### AGPAなし ❌ - セッションをまたいだコーディング習慣の**可視性なし** - **進捗の追跡不可** — 速くなってる？ツールを増やしてる？知る術がない - エージェントの全機能を探求する**モチベーションなし** - **毎日同じルーティン** — 驚きもマイルストーンもない ### AGPAあり ✅ - **自動トラッキング** — すべてのツール呼び出し、ファイル編集、Gitコミットが自動記録 - **Steam風ダッシュボード** — XPバー、レベル、連続記録、ヒートマップ、実績ショーケース - **217個の実績**、11カテゴリ — 「Hello World」から「コンプリート」まで - **即時フィードバック** — ターミナルポップアップ、macOS通知、8ビットサウンド --- ## クイックスタート **前提条件:** Node.js ≥ 18 ```bash # 方法A: グローバルインストール（一般ユーザー向け） npm install -g @eiainano/agpa agpa init # 方法B: クローンしてリンク（コントリビューター向け） git clone https://github.com/eiainano/AgentPlayerAchievements.git cd AgentPlayerAchievements && npm install && npm link agpa init ``` 以上です。エージェントを使い続けてください — 作業中に実績が自動的に解除されます。 > [!TIP] > 実際の解除を待たずにダッシュボードを見てみたい？`agpa demo`を実行すればサンプルデータが即座に生成されます。 ```bash agpa dashboard # 実績ダッシュボードを開く agpa stats # 進捗を確認 agpa assets download # (オプション) 219枚のピクセルアートバッジを一括ダウンロード ``` ## 仕組み ``` コーディングセッション │ ├─ コードを書き、エージェントが応答 — すべてのアクションが追跡される │ └─ デュアルチャネル: MCPツール + Hookイベント │ ├─ セッション終了 → エンジンが217個の実績を評価 │ └─ 解除された？ → macOS通知 🎉 │ └─ agpa dashboard → 表示、並べ替え、フィルター、共有 ``` **2つのデータチャネル → 1つのエンジン → 1つのダッシュボード:** | チャネル | 方式 | キャプチャ内容 | |---------|--------|----------| | **Hook CLI** | ツールフック（stdin経由のサブプロセス） | file.read/write/edit, tool.complete, git.commit, session.start/end, task.complete, agent.spawn | | **MCPサーバー** | STDIOプロトコル（7ツール） | image.read, file.language_used, plan.mode_entered, user.message, automode.start | 両方のチャネルが同じ `~/.agent-achievements/` イベントログに書き込みます。エンジンは12種類の条件タイプで217個の実績を評価します。 > [!NOTE] > **オーバーヘッドゼロ。** Hook CLIは1ミリ秒未満のサブプロセスです。MCPサーバーはネットワーク呼び出しなしでSTDIO上で動作します。すべてのデータはあなたのマシン上に留まります。 ## 機能 - 🎮 **実績ダッシュボード** — XPバー、レベル、連続記録、アクティビティヒートマップ、レア度内訳、ショーケース - 🏆 **217個の実績**、11カテゴリ — 「Hello World」から「コンプリート」まで - 🔥 **GitHub風アクティビティヒートマップ** — 4ヶ月分のコーディングアクティビティを一目で - 📸 **共有カード** — ダーク/ライトテーマ、バイリンガル、PNGダウンロード可能 - 🔊 **8ビットサウンドエフェクトと通知** — レア度別のレトロな解除音 + デスクトッププッシュ通知 - 📂 **マルチプロファイル** — 最大4プロファイル、いつでも切り替え可能（仕事、個人、実験） ## 対応ツール

| ツール | 自動トラック | MCPトラック | 最も簡単なセットアップ | |------|:----------:|:---------:|---------------| | Claude Code | ✅ | ✅ | `agpa init`が自動検出 | | Kilo Code | ✅ | ✅ | TSプラグイン + MCP設定 | | OpenCode | ✅ | ✅ | TSプラグイン + MCP設定 | | Hermes | — | ✅ | MCP JSON設定 | | OpenClaw | ✅ | ✅ | プラグイン + MCP設定 | Hermes（Hook APIなし）を除く全ツールで完全なデュアルチャネルカバレッジを提供します。MCP互換クライアント（Cursor、VS Code、Windsurfなど）では、MCPのみのトラッキングがそのまま動作します — Hookベースの自動トラッキングだけが欠けます。 > [!TIP] > **MCPは初めてですか？** `agpa init`から始めましょう — インストール済みのツールを自動検出し、すべてを設定します。以下の手動JSON設定は代替手段です。

Claude Code — 自動トラック + MCP（完全カバレッジ）

`agpa init`がClaude Codeを自動検出し、両方のチャネルを登録します。手動セットアップ： **MCP設定** (`~/.claude/.mcp.json` またはプロジェクトルートの `.mcp.json`): ```json { "mcpServers": { "agpa": { "command": "npx", "args": ["-y", "@eiainano/agpa", "agpa-mcp"] } } } ``` **Hook登録** — `agpa init`がClaude Code設定にHookエントリを追加します。`agpa verify`で確認してください。

Cursor / VS Code — MCPのみ

これらのエディタはMCPをサポートしていますが、自動トラッキング用のHook APIを公開していません。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 — 自動トラック + MCP（完全カバレッジ）

これらのツールはHookレベルの自動トラッキング用のTSプラグインをサポートしています。`agpa init`がプラグイン + MCP設定を登録します。 **手動MCP設定** (`opencode.json` または Kilo Code設定): ```json { "mcpServers": { "agpa": { "command": "npx", "args": ["-y", "@eiainano/agpa", "agpa-mcp"] } } } ``` `agpa init`によって登録されたTSプラグインが、PostToolUse、SessionStart、SessionEnd、その他のHookイベントを自動的に処理します。

Hermes — MCPのみ

HermesはHook APIを公開していません。MCPベースのトラッキングがツール呼び出しとセッションイベントをカバーします。 **MCP設定** (`~/.hermes/mcp.json`): ```json { "mcpServers": { "agpa": { "command": "npx", "args": ["-y", "@eiainano/agpa", "agpa-mcp"] } } } ```

OpenClaw — 自動トラック + MCP（完全カバレッジ）

OpenClawはHookレベルのトラッキング用のプラグインシステムをサポートしています。`agpa init`がプラグインとMCP設定の両方を登録します。 **手動MCP設定**: ```json { "mcpServers": { "agpa": { "command": "npx", "args": ["-y", "@eiainano/agpa", "agpa-mcp"] } } } ```

## CLIコマンド | コマンド | 説明 | |---------|-------------| | `agpa init` | エージェントツールを自動検出して登録 | | `agpa uninstall` | 設定済みの全ツールからAGPAをクリーンに削除 | | `agpa verify` | インストールの正しさを確認 | | `agpa doctor` | システム状態を診断 | | `agpa dashboard` | 実績ダッシュボードを起動（localhost:3867） | | `agpa stats` | 実績進捗サマリーを表示 | | `agpa progress` | 全実績を解除状態とともに一覧表示 | | `agpa profile` | 実績プロファイルを管理（作成、一覧、切り替え、ソフトウェア、削除） | | `agpa demo` | テスト用のMVPデモデータを生成 | | `agpa reset` | すべてのトラッキングデータをリセット | | `agpa config` | 設定の表示/変更（言語、サウンド、デバッグ...） | | `agpa showcase` | ショーケースを管理（一覧、固定、解除、自動入力） | | `agpa search` | キーワード/レア度/カテゴリで実績を検索 | | `agpa suggest` | 次に狙う実績を提案 | | `agpa sound` | 8ビットレア度別サウンドエフェクトを切り替え (on, off) | | `agpa activity` | 連続記録 + 4ヶ月のアクティビティヒートマップを表示 | | `agpa export` | 実績データをJSONとしてエクスポート | | `agpa import` | バックアップからインポート | | `agpa mcp` | MCPサーバーを起動（stdioモード） | | `agpa web` | `agpa dashboard`のエイリアス | | `agpa pack` | インストール済みのコミュニティ実績パックを一覧・表示 | | `agpa banner` | CLIバナーのカラーテーマ切替 (Neon/Arcade/Gold) | | `agpa history` | イベントログエントリを閲覧 | | `agpa explain` | 実績のロック/解除理由を表示（条件分析） | | `agpa watch` | リアルタイム実績進捗モニター | | `agpa upgrade` | アップデートを確認してAGPAをアップグレード | | `agpa completion` | シェル補完スクリプト生成 (bash/zsh/fish) | > 完全なCLIリファレンス: `agpa --help` ## コミュニティパック誰でも実績パックを作成して共有できます。YAMLファイルを`~/.agent-achievements/packs/`に置くだけでインストール完了です： ```bash agpa pack list # インストール済みパックを一覧表示 agpa pack info # パックの詳細を表示 ``` パック形式、イベントカタログ、12の条件タイプについては[実績パック作成ガイド](docs/creating-achievements.md)を参照してください。 ## ダッシュボード

統計行 → 連続記録 + ヒートマップ → ショーケース → 検索/フィルター付き実績グリッド

```bash agpa dashboard # デフォルトポート :3867 agpa dashboard 8080 # カスタムポート agpa dashboard --profile work # 特定のプロファイルで起動 ``` - **統計**: XP、レベル、総実績数、連続記録、タスク、ツール使用 - **ヒートマップ**: GitHub風4ヶ月アクティビティグリッド - **ショーケース**: 固定されたお気に入り実績（最大6個） - **実績グリッド**: 検索、レア度/カテゴリでソート、解除/ロックでフィルター - **サウンドトグル**: 8ビットレア度別エフェクト - **共有ボタン**: 美しいバイリンガルカードを生成 → PNGダウンロード ## アーキテクチャ ``` ┌─────────────────────────┐ │ エンジン (src/engine/) │ │ track() / poll() │ └─────────────────────────┘ ↗ ↖ MCPサーバー Hook CLI (src/main.ts) (src/cli/hook.ts) │ │ STDIO永続接続短命サブプロセス │ (stdin pipe) │ │ エージェントがフックが自動的に意識的に呼び出す発火 │ │ ┌─────┴─────┐ ┌──────┴──────┐ │ 手動トラック│ │ 自動トラック│ │ image.read │ │ tool.complete│ │ lang_used │ │ file.edit │ │ plan.mode │ │ session.* │ │ ... │ │ agent.spawn │ └───────────┘ └─────────────┘ ╲ ╱ event.log ← 両チャネルがここに書き込み │ engine.poll() │ state.json │ ダッシュボード ``` ## プロジェクト構造 ``` src/ ├── main.ts # MCPサーバーエントリ (STDIO) ├── tool-registry.ts # 中央ツール登録 ├── cli/ │ ├── index.ts # 統一CLIエントリ (27コマンド) │ ├── hook.ts # Hook CLI (track + poll + auto モード) │ ├── init.ts # 対話型インストールウィザード │ ├── dashboard.ts # ダッシュボードランチャー │ ├── doctor.ts # システム診断 │ │ └── ... # 22のCLIコマンド ├── engine/ │ ├── engine.ts # コアエンジン (track / poll / stats) │ ├── evaluator.ts # 12種類の条件タイプ評価器 │ ├── store.ts # JSONLイベントログ + 状態永続化 │ ├── types.ts # TypeScriptインターフェース │ └── yaml-parser.ts # YAML実績定義パーサー ├── dashboard/ │ ├── server.ts # HTTPサーバー + APIルート │ ├── api.ts # カードデータ、統計集計 │ ├── public/ # ゼロフレームワーク HTML/CSS/JS フロントエンド │ └── customize-api.ts # セルフカスタマイズエンドポイント ├── tools/ # MCPツール定義 (7ツール) ├── utils/ # 通知、検証、プロファイル、ピクセルアート、バッテリー等 ├── verify/ │ └── auditor.ts # 実績検証ロジック ├── config.ts # グローバル設定 └── helpers.ts # 共有ユーティリティ pixel-art-output/ # ロゴ (README) achievement-definitions.yaml # 217個の実績定義（信頼できるデータソース） scripts/ # 開発ツール（ロゴ生成、ピクセルアート生成、サウンド） ``` ## 🔒 セキュリティとプライバシー - **ローカルファースト** — すべてのイベントデータは `~/.agent-achievements/` に保存。テレメトリなし、クラウド同期なし、ランタイム時のネットワーク呼び出しなし。 - **監査可能** — エンジンはJSONLファイルを操作する純粋なTypeScript関数。難読化なし、バイナリなし。 - **最小限の依存関係** — 5つのランタイム依存関係（`@modelcontextprotocol/sdk`、`yaml`、`zod`、`figlet`）— すべて広く監査済み。 - **STDIO分離** — MCPサーバーは標準I/Oのみで通信。HTTPエンドポイントは公開されません。 - **Hookサンドボックス** — Hook CLIは1ミリ秒未満のサブプロセスとして実行され、状態の永続化やネットワークアクセスはできません。 - **サプライチェーン** — ネイティブモジュールなし、postinstallスクリプトなし、インストール時のバイナリダウンロードなし。脆弱性を報告するには、[SECURITY.md](SECURITY.md) をご覧ください。 ## 👥 コントリビューションコントリビューションを歓迎します！実績パック、ダッシュボードの改善、新しいツール統合、エンジンの修正など、あらゆるスキルレベルに参加方法があります。 - **[CONTRIBUTING.md](CONTRIBUTING.md)** — セットアップ、コーディング規約、PRプロセス、4つのコントリビューションパス - **[実績パック作成ガイド](docs/creating-achievements.md)** — 実績定義の完全な作成ガイド - **[`.github/ISSUE_TEMPLATE/`](.github/ISSUE_TEMPLATE/)** — IssueとPRのテンプレート ## 🌐 環境変数 | 変数 | 説明 | デフォルト | 値 | |----------|-------------|---------|--------| | `AGPA_PROFILE` | アクティブなプロファイル名 | `default` | 任意の文字列 | | `AGPA_LANG` | インターフェース言語 | `en` | `en`, `zh` | | `AGPA_ENABLED_CATEGORIES` | アクティブな実績カテゴリをフィルター | すべて | カンマ区切り（例: `onboarding,tool_mastery`） | | `AGPA_DEBUG` | 詳細なデバッグログを有効化 | `false` | `true` | | `AGPA_SOUND` | サウンドエフェクトを上書き | 設定値 | `on`, `off`, `true`, `false` | | `AGPA_SIMPLE_ANIMATIONS` | 簡略化されたターミナルアニメーションを使用 | `false` | `true` | | `AGPA_BANNER_THEME` | CLI起動バナースタイル | `Arcade` | `Neon`, `Arcade`, `Gold` | | `AGPA_TELEMETRY` | 匿名使用テレメトリを有効化 | `false` | `true`, `false` | | `AGPA_TELEMETRY_SERVER` | カスタムテレメトリエンドポイントURL | `''` (なし) | URL文字列 | | `AGPA_TOOL_SOURCE` | ツールソース識別子を上書き | 自動検出 | `claude-code`, `hermes`, `openclaw` など | | `AGPA_MODEL` | 現在のAIモデル名（実績用） | `auto` | 任意のモデル文字列 | > [!TIP] > 環境変数は `config.json` の設定を上書きします。永続的な上書きにはシェルプロファイルまたはエージェント設定で指定してください。 ## よくある質問 **Q: エージェントが遅くなりますか？** A: いいえ。Hook CLIは1ミリ秒未満のサブプロセスです。MCPサーバーはネットワークオーバーヘッドなしでSTDIO上で動作します。 **Q: 複数のエージェントで使用できますか？** A: はい。インストールウィザードがClaude Code、Kilo Code、OpenCode、Hermes、OpenClawを自動検出します。それぞれに独自のプロファイルを持たせることができます。 **Q: 実績が解除されません？** A: `agpa doctor`を実行してください — トラッキング状態、Hook登録、イベントカバレッジを診断します。 **Q: WakaTimeや他のコーディングアクティビティトラッカーとはどう違いますか？** A: WakaTimeは*何を*したかを教えます — 時間、言語、プロジェクト。AGPAはそれを*楽しく*します — XP、レベル、実績、連続記録、Steam風のドーパミンヒット。既存のワークフローに重ねたゲーミフィケーションであり、確認すべきもう一つのダッシュボードではありません。フィットネストラッカーの歩数カウントとPokémon Goのバッジの違いを想像してください — 同じデータ、異なる体験。 **Q: 実績名をカスタマイズできますか？** A: はい。ダッシュボードの `/customize` ページで任意の実績名を変更できます。 ## トラブルシューティング > [!IMPORTANT] > **あらゆる問題の最初のステップ:** `agpa doctor`を実行してください — トラッキング状態、Hook登録、イベントカバレッジ、設定の問題を一度に診断します。 | 症状 | 考えられる原因 | 修正方法 | |---------|-------------|-----| | 実績が解除されない | Hook/MCPが登録されていない | `agpa doctor`を実行してHook登録 + イベントカバレッジを確認 | | ダッシュボードが起動しない | ポート3867が既に使用中 | `agpa dashboard 8080`（または任意の空きポート） | | `agpa init`が失敗 | エージェントツールが検出されない | 対応ツールリストを確認; 代替として手動MCP JSON設定を使用 | | macOS通知が来ない | `terminal-notifier`がない | `brew install terminal-notifier`を実行、または`agpa init`が自動インストール | | サウンドが再生されない | ブラウザのオーディオコンテキストがブロックされている | ダッシュボードページの任意の場所をクリックしてオーディオを有効化 | | プロファイル切り替えが機能しない | プロファイルが存在しない | `agpa profile list`で利用可能なプロファイルを確認し、`agpa profile switch `を実行 | | エージェントログにHook CLIエラー | stdin pipeが空（初回実行時は正常） | 正常 — Hookは短命サブプロセス; エラーは `~/.agent-achievements/error.log` に記録されます | 継続的な問題は `~/.agent-achievements/error.log` を確認するか、[Issueを作成](https://github.com/eiainano/AgentPlayerAchievements/issues)してください。 ## スター履歴

## ライセンス MIT — [LICENSE](LICENSE) を参照

_{ホーム — XPバー、連続記録、エージェント統計}	_{成就 — 217個の実績 × 11カテゴリ}
_{套装 — テーマコレクション × 進捗}	_{詳細カード — レア度、解除日、リプレイ}