AgentPlayerAchievements

Agent Player Achievements (AGPA) 🏆

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

Sistema de logros gamificado para agentes de codificación de IA.
Gana XP, desbloquea trofeos, sube de nivel — solo haciendo lo que ya haces.

Claude Code · Kilo Code · OpenCode · Hermes · OpenClaw

Inicio rápido · Cómo funciona · Características · Herramientas compatibles · Comandos CLI · Paquetes comunitarios · Panel · Seguridad y privacidad · Contribuir · FAQ

Sin AGPA ❌

• Sin visibilidad de tus hábitos de codificación entre sesiones
• No puedes seguir tu progreso — ¿vas más rápido? ¿Usas más herramientas? No hay forma de saberlo
• Sin motivación para explorar todas las funciones de tu agente
• La misma rutina todos los días — sin sorpresas, sin hitos

Con AGPA ✅

• Seguimiento automático — cada llamada a herramienta, edición de archivo y commit de git se registra automáticamente
• Panel estilo Steam — barra de XP, niveles, rachas, mapas de calor, vitrina de logros
• 217 logros en 11 categorías — desde "Hello World" hasta "Completionist"
• Retroalimentación instantánea — ventanas emergentes en terminal, notificaciones de macOS, sonidos de 8 bits al desbloquear

Vista previa del panel

Inicio — barra de XP, rachas, estadísticas del agente	Logros — 217 logros × 11 categorías
Conjuntos — colecciones temáticas con seguimiento de progreso	Tarjeta de detalle — rareza, fecha de desbloqueo, animación de repetición

Inicio rápido

Requisitos previos: 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

Eso es todo. Sigue usando tu agente — los logros se desbloquean automáticamente mientras trabajas.

[!TIP] ¿Quieres ver cómo se ve el panel sin esperar desbloqueos reales? Ejecuta agpa demo para generar datos de muestra al instante.

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

Cómo funciona

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

Dos canales de datos → un motor → un panel:

Ambos canales escriben en el mismo registro de eventos ~/.agent-achievements/. El motor evalúa 12 tipos de condiciones contra 217 logros.

[!NOTE] Cero sobrecarga. El Hook CLI es un subproceso de sub-milisegundo. El servidor MCP se ejecuta en STDIO sin llamadas de red. Todos los datos permanecen en tu máquina.

Características

• 🎮 Panel de logros — barra de XP, nivel, racha, mapa de calor de actividad, desglose de rareza, vitrina
• 🏆 217 logros en 11 categorías — desde "Hello World" hasta "Completionist"
• 🔥 Mapa de calor de actividad estilo GitHub — 4 meses de actividad de codificación de un vistazo
• 📸 Tarjeta para compartir — tema claro/oscuro, bilingüe, PNG descargable
• 🔊 Efectos de sonido y notificaciones de 8 bits — sonidos retro graduados por rareza + notificaciones push de escritorio al desbloquear
• 📂 Multi-perfil — hasta 4 perfiles, cambia cuando quieras (trabajo, personal, experimentación)

Herramientas compatibles

Las cinco herramientas tienen cobertura completa de doble canal excepto Hermes (sin API de hooks). Para cualquier cliente compatible con MCP (Cursor, VS Code, Windsurf, etc.), el seguimiento solo con MCP funciona de inmediato — solo te pierdes el auto-seguimiento basado en hooks.

[!TIP] ¿Nuevo en MCP? Empieza con agpa init — detecta automáticamente tus herramientas instaladas y configura todo. Las configuraciones JSON manuales a continuación son alternativas.

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

Servidor MCP

AGPA ejecuta un servidor Model Context Protocol (transporte stdio) que expone 7 herramientas para cualquier cliente compatible con MCP — Claude Desktop, Cursor, VS Code, Windsurf y más.

Inicio rápido con cualquier cliente MCP:

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

¿Ya tienes AGPA instalado globalmente? Ejecuta agpa-mcp directamente. El servidor detecta automáticamente tu perfil activo y la fuente de la herramienta.

Comandos CLI

Referencia completa de CLI: agpa --help

Paquetes comunitarios

Cualquiera puede crear y compartir paquetes de logros. Coloca un archivo YAML en ~/.agent-achievements/packs/ para instalarlo:

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

Consulta Creación de paquetes de logros para la especificación del formato de paquete, el catálogo de tipos de eventos y los 12 tipos de condiciones.

Panel

Fila de estadísticas → Racha + Mapa de calor → Vitrina → Cuadrícula de logros con búsqueda/filtro

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

• Estadísticas: XP, nivel, logros totales, racha, tareas, usos de herramientas
• Mapa de calor: cuadrícula de actividad de 4 meses estilo GitHub
• Vitrina: logros favoritos fijados (hasta 6)
• Cuadrícula de logros: búsqueda, ordenar por rareza/categoría, filtrar desbloqueados/bloqueados
• Alternar sonido: efectos de 8 bits clasificados por rareza
• Botón de compartir: genera una hermosa tarjeta bilingüe → descarga PNG

Arquitectura

                    ┌─────────────────────────┐
                    │   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

Estructura del Proyecto

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)

🔒 Seguridad y Privacidad

• Local primero — Todos los datos de eventos permanecen en ~/.agent-achievements/. Sin telemetría, sin sincronización en la nube, sin llamadas de red en tiempo de ejecución.
• Auditable — El motor son funciones puras de TypeScript que operan sobre archivos JSONL. Sin ofuscación, sin blobs binarios.
• Dependencias mínimas — 5 dependencias de ejecución (@modelcontextprotocol/sdk, yaml, zod, figlet, tsx) — todas ampliamente auditadas.
• Aislamiento STDIO — El servidor MCP se comunica solo mediante E/S estándar. No se exponen endpoints HTTP.
• Sandbox de Hook — La CLI de Hook se ejecuta como un subproceso de sub-milisegundo — no puede persistir estado ni acceder a la red.
• Cadena de suministro — Sin módulos nativos, sin scripts de postinstalación, sin descargas binarias en la instalación.

Para reportar una vulnerabilidad, consulta SECURITY.md.

👥 Contribuciones

¡Damos la bienvenida a contribuciones! Ya sea un paquete de logros, una mejora del Dashboard, una nueva integración de herramienta o una corrección del motor — hay un camino para cada nivel de habilidad.

• CONTRIBUTING.md — configuración, convenciones de código, proceso de PR y 4 rutas de contribución
• Creación de paquetes de logros — la guía completa para escribir definiciones de logros
• .github/ISSUE_TEMPLATE/ — plantillas de issues y PRs

🌐 Variables de Entorno

[!TIP] Las variables de entorno sobrescriben la configuración de config.json. Configúralas en tu perfil de shell o en la configuración del agente para sobrescrituras persistentes.

Preguntas Frecuentes

P: ¿Esto ralentiza mi agente? R: No. La CLI de Hook es un subproceso de sub-milisegundo. El servidor MCP se ejecuta en STDIO con cero sobrecarga de red.

P: ¿Puedo usarlo con múltiples agentes? R: Sí. El asistente de inicialización detecta automáticamente Claude Code, Kilo Code, OpenCode, Hermes y OpenClaw. Cada uno puede tener su propio perfil.

P: ¿Mis logros no se desbloquean? R: Ejecuta agpa doctor — diagnostica el estado de seguimiento, el registro de hooks y la cobertura de eventos.

P: ¿En qué se diferencia de WakaTime o de los rastreadores de actividad de codificación? R: WakaTime te dice qué hiciste — horas, lenguajes, proyectos. AGPA lo hace divertido — XP, niveles, logros, rachas y descargas de dopamina estilo Steam. Es gamificación superpuesta a tu flujo de trabajo existente, no otro panel que revisar. Piénsalo como la diferencia entre el conteo de pasos crudo de un rastreador de fitness y una insignia de Pokémon Go — mismos datos, experiencia diferente.

P: ¿Puedo personalizar los nombres de los logros? R: Sí. La página /customize en el panel te permite renombrar cualquier logro.

Solución de Problemas

[!IMPORTANT] Primer paso para cualquier problema: Ejecuta agpa doctor — diagnostica el estado de seguimiento, el registro de hooks, la cobertura de eventos y los problemas de configuración de una sola vez.

Para problemas persistentes, revisa ~/.agent-achievements/error.log o abre un issue.

Historial de Estrellas

Licencia

MIT — consulta LICENSE