AgentPlayerAchievements

Agent Player Achievements (AGPA) 🏆

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

Sistema de conquistas gamificado para agentes de codificação de IA.
Ganhe XP, desbloqueie troféus, suba de nível — apenas fazendo o que você já faz.

Claude Code · Kilo Code · OpenCode · Hermes · OpenClaw

Início Rápido · Como Funciona · Recursos · Ferramentas Suportadas · Comandos CLI · Pacotes da Comunidade · Painel · Segurança e Privacidade · Contribuindo · FAQ

Sem AGPA ❌

• Sem visibilidade dos seus hábitos de codificação entre sessões
• Não consegue acompanhar o progresso — está ficando mais rápido? Usando mais ferramentas? Não há como saber
• Sem motivação para explorar todo o conjunto de recursos do seu agente
• Mesma rotina todos os dias — sem surpresas, sem marcos

Com AGPA ✅

• Rastreamento automático — cada chamada de ferramenta, edição de arquivo e commit git registrado automaticamente
• Painel estilo Steam — barra de XP, níveis, sequências, mapas de calor, vitrine de conquistas
• 217 conquistas em 11 categorias — de "Hello World" a "Completionist"
• Feedback instantâneo — popups no terminal, notificações do macOS, sons de 8 bits ao desbloquear

Prévia do Painel

Início — barra de XP, sequências, estatísticas do agente	Conquistas — 217 conquistas × 11 categorias
Conjuntos — coleções temáticas com acompanhamento de progresso	Cartão de Detalhes — raridade, data de desbloqueio, animação de repetição

Início Rápido

Pré-requisitos: 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

É isso. Continue usando seu agente — as conquistas desbloqueiam automaticamente enquanto você trabalha.

[!TIP] Quer ver como o painel fica sem esperar por desbloqueios reais? Execute agpa demo para gerar dados de exemplo instantaneamente.

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

Como 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

Dois canais de dados → um mecanismo → um painel:

Ambos os canais gravam no mesmo log de eventos ~/.agent-achievements/. O mecanismo avalia 12 tipos de condição contra 217 conquistas.

[!NOTE] Zero sobrecarga. O Hook CLI é um subprocesso de submilissegundo. O servidor MCP roda em STDIO sem chamadas de rede. Todos os dados permanecem na sua máquina.

Recursos

• 🎮 Painel de Conquistas — barra de XP, nível, sequência, mapa de calor de atividade, detalhamento de raridade, vitrine
• 🏆 217 Conquistas em 11 categorias — de "Hello World" a "Completionist"
• 🔥 Mapa de calor de atividade estilo GitHub — 4 meses de atividade de codificação de relance
• 📸 Cartão de Compartilhamento — tema escuro/claro, bilíngue, PNG para download
• 🔊 Efeitos sonoros e notificações de 8 bits — sons retrô graduados por raridade + notificações push na área de trabalho ao desbloquear
• 📂 Multi-perfil — até 4 perfis, alterne a qualquer momento (trabalho, pessoal, experimentação)

Ferramentas Suportadas

Todas as cinco ferramentas têm cobertura total de canal duplo, exceto Hermes (sem API de hook). Para qualquer cliente compatível com MCP (Cursor, VS Code, Windsurf, etc.), o rastreamento somente MCP funciona imediatamente — você apenas perde o rastreamento automático baseado em hooks.

[!TIP] Novo no MCP? Comece com agpa init — ele detecta automaticamente suas ferramentas instaladas e configura tudo. Configs JSON manuais abaixo são 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 executa um servidor Model Context Protocol (transporte stdio) que expõe 7 ferramentas para qualquer cliente compatível com MCP — Claude Desktop, Cursor, VS Code, Windsurf e outros.

Início rápido com qualquer cliente MCP:

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

Já instalou o AGPA globalmente? Execute agpa-mcp diretamente. O servidor detecta automaticamente seu perfil ativo e a origem da ferramenta.

Comandos CLI

Referência completa da CLI: agpa --help

Pacotes da Comunidade

Qualquer pessoa pode criar e compartilhar pacotes de conquistas. Coloque um arquivo YAML em ~/.agent-achievements/packs/ para instalar:

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

Veja Criando Pacotes de Conquistas para a especificação do formato do pacote, catálogo de tipos de evento e 12 tipos de condição.

Painel

Linha de estatísticas → Sequência + Mapa de calor → Vitrine → Grade de conquistas com busca/filtro

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

• Estatísticas: XP, nível, conquistas totais, sequência, tarefas, usos de ferramentas
• Mapa de calor: grade de atividade de 4 meses no estilo GitHub
• Vitrine: conquistas favoritas fixadas (até 6)
• Grade de Conquistas: busca, ordenação por raridade/categoria, filtro desbloqueadas/bloqueadas
• Alternância de som: efeitos de 8 bits classificados por raridade
• Botão de compartilhar: gera um belo cartão bilíngue → download em PNG

Arquitetura

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

Estrutura do Projeto

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)

🔒 Segurança e Privacidade

• Local-first — Todos os dados de eventos permanecem em ~/.agent-achievements/. Sem telemetria, sem sincronização em nuvem, sem chamadas de rede em tempo de execução.
• Auditável — O motor é composto por funções TypeScript puras que operam em arquivos JSONL. Sem ofuscação, sem blobs binários.
• Dependências mínimas — 5 dependências de tempo de execução (@modelcontextprotocol/sdk, yaml, zod, figlet, tsx) — todas amplamente auditadas.
• Isolamento STDIO — O servidor MCP se comunica apenas via entrada/saída padrão. Nenhum endpoint HTTP exposto.
• Sandbox de hooks — O Hook CLI é executado como um subprocesso de submilissegundo — ele não pode persistir estado ou acessar a rede.
• Cadeia de suprimentos — Sem módulos nativos, sem scripts de pós-instalação, sem downloads binários na instalação.

Para relatar uma vulnerabilidade, consulte SECURITY.md.

👥 Contribuindo

Aceitamos contribuições! Seja um pacote de conquistas, uma melhoria no Dashboard, uma nova integração de ferramenta ou uma correção no motor — há um caminho para cada nível de habilidade.

• CONTRIBUTING.md — configuração, convenções de código, processo de PR e 4 caminhos de contribuição
• Criando Pacotes de Conquistas — o guia completo para escrever definições de conquistas
• .github/ISSUE_TEMPLATE/ — modelos de issue e PR

🌐 Variáveis de Ambiente

[!TIP] As variáveis de ambiente substituem as configurações de config.json. Defina-as no seu perfil de shell ou na configuração do agente para substituições persistentes.

FAQ

P: Isso deixa meu agente mais lento? R: Não. O Hook CLI é um subprocesso de submilissegundo. O servidor MCP roda em STDIO com zero sobrecarga de rede.

P: Posso usar com vários agentes? R: Sim. O assistente de inicialização detecta automaticamente Claude Code, Kilo Code, OpenCode, Hermes e OpenClaw. Cada um pode ter seu próprio perfil.

P: Minhas conquistas não estão desbloqueando? R: Execute agpa doctor — ele diagnostica o status de rastreamento, registro de hooks e cobertura de eventos.

P: Qual é a diferença entre isso e o WakaTime ou rastreadores de atividade de codificação? R: O WakaTime informa o que você fez — horas, linguagens, projetos. O AGPA torna isso divertido — XP, níveis, conquistas, sequências e doses de dopamina no estilo Steam. É gamificação aplicada sobre seu fluxo de trabalho existente, não outro painel para verificar. Pense como a diferença entre a contagem bruta de passos de um rastreador de fitness e uma medalha do Pokémon Go — mesmos dados, experiência diferente.

P: Posso personalizar os nomes das conquistas? R: Sim. A página /customize no dashboard permite renomear qualquer conquista.

Solução de Problemas

[!IMPORTANT] Primeiro passo para qualquer problema: Execute agpa doctor — ele diagnostica status de rastreamento, registro de hooks, cobertura de eventos e problemas de configuração de uma só vez.

Para problemas persistentes, verifique ~/.agent-achievements/error.log ou abra uma issue.

Histórico de Estrelas

Licença

MIT — consulte LICENSE