O que é o AgentDeck?

AgentDeck é um plugin para Stream Deck que traz suas sessões de agentes de IA para fora do terminal e as coloca em hardware físico. Cada tecla do Stream Deck mapeia para uma instância em execução do Claude Code, Gemini CLI ou Cursor Agent — exibindo o status em tempo real com ícones animados, respondendo a gestos como focar, cancelar e aprovar, e rastreando o uso de tokens e custo enquanto você trabalha.

A ideia é simples: quando você está rodando múltiplos agentes em múltiplos projetos, perde a percepção da situação rapidamente. O AgentDeck fornece uma superfície de controle física — sem mais alt-tab para verificar se um agente está aguardando permissão ou encontrou um erro.

O Problema que Resolve

Agentes de IA headless são poderosos, mas opacos. Eles rodam em terminais, bloqueiam em permissões, lançam erros e consomem tokens — e nada disso é visível a menos que você esteja ativamente observando a janela certa. Quando você tem três ou quatro sessões abertas em diferentes projetos, acompanhar o que cada agente está fazendo vira um custo constante de troca de contexto.

O AgentDeck externaliza essa carga cognitiva para um hardware dedicado. Um olhar no Stream Deck e você sabe quais agentes estão rodando, quais aguardam sua aprovação e quais já terminaram — sem tocar no teclado.

Funcionalidades Principais

Ícones de Status Animados

Cada tecla renderiza um ícone de status animado a 12 FPS, refletindo o estado atual do agente:

Controles por Gesto

Três gestos por tecla, sem configuração:

• Pressão simples — foca a janela do terminal que executa aquele agente
• Pressão dupla — cancela a operação atual (envia SIGINT)
• Segurar (500ms) — aprova uma solicitação de permissão pendente

Suporte Multi-Instância

Atribua teclas diferentes do Stream Deck a instâncias diferentes de agentes. A atribuição automática baseada em pasta de projeto ou ID de sessão faz a tecla certa acender para o projeto certo automaticamente.

Rastreamento de Tokens e Custo

O AgentDeck escaneia os logs de sessão do Claude Code em tempo real, extrai contagens de tokens (entrada, saída, cache read, cache write) e calcula o custo acumulado usando preços atualizados dos modelos Claude Opus 4, Sonnet 4 e Haiku 4. Mude o modo de exibição de uma tecla para ver tokens ou custo em vez do ícone de status.

Modos de exibição por tecla:
  status   → ícone animado
  tokens   → contagem de tokens entrada / saída
  cost     → custo atual da sessão em USD
  activity → log de atividades recentes

Como Funciona

Claude Code / Gemini CLI / Cursor
        │
   hooks de ciclo de vida (SessionStart, PreToolUse,
   PermissionRequest, Stop, …)
        │
        ▼
  status-reporter.sh  →  HTTP POST /status
                               │
                         localhost:19847
                               │
                         StatusServer (HTTP + WebSocket)
                               │
                    ┌──────────┴──────────┐
                    │                     │
              InstanceManager       UsageTracker
              (lógica de estado     (escaneamento
               persistente)          de logs)
                    │
                    ▼
            Plugin do Stream Deck
            (ícones animados + gestos)

O plugin executa um servidor local leve na porta 19847. Os hooks do Claude Code disparam em eventos de ciclo de vida e enviam HTTP POSTs para esse servidor. O servidor transmite atualizações para todos os clientes Stream Deck conectados via WebSocket. O plugin renderiza ícones e trata eventos de gesto na direção contrária.

Lógica de Estado Persistente

Os estados permission e question são "pegajosos" — persistem mesmo quando atualizações idle ou running chegam, evitando oscilação de ícone enquanto o agente imprime texto após uma pergunta. Os estados só são limpos quando um hook de progresso dispara (PreToolUse, PostToolUse, Stop, SessionEnd).

Integrações

Hooks do Claude Code

O AgentDeck funciona via sistema de hooks do Claude Code. Adicione o script de hook fornecido ao seu ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart":       [{ "command": "status-reporter.sh session_start" }],
    "SessionEnd":         [{ "command": "status-reporter.sh session_end" }],
    "PreToolUse":         [{ "command": "status-reporter.sh pre_tool_use" }],
    "PostToolUse":        [{ "command": "status-reporter.sh post_tool_use" }],
    "PermissionRequest":  [{ "command": "status-reporter.sh permission" }],
    "Stop":               [{ "command": "status-reporter.sh stop" }],
    "Notification":       [{ "command": "status-reporter.sh notification" }]
  }
}

Terminal Kitty

O AgentDeck tem suporte de primeira classe ao Kitty via API de controle remoto kitten @. Detecta automaticamente sockets (KITTY_LISTEN_ON, /tmp/kitty, /tmp/kitty-*), testa cada candidato antes de usar e recai para um lançamento direto do Kitty se o controle remoto não estiver disponível. Requer allow_remote_control yes no kitty.conf.

Adaptadores AppleScript (macOS) e PowerShell (Windows) tratam o foco de terminal para outros emuladores.

Stack Técnica

• TypeScript 5.7 — modo strict, empacotado com Rollup
• @elgato/streamdeck 1.2 — SDK oficial do Stream Deck
• ws — servidor WebSocket para push em tempo real ao plugin
• sharp — renderização de ícones SVG → PNG por frame
• Node.js 20+, Stream Deck 6.6+

Status

O AgentDeck está em desenvolvimento ativo. O suporte atual cobre Claude Code, Gemini CLI e Cursor Agent. Adições planejadas incluem mais adaptadores de terminal (iTerm2, WezTerm, Ghostty, Alacritty), exportação de histórico de sessões, alertas de custo por limites e integração com OpenAI CLI.