Claude Code HUD

Instruções da skill

---
name: claude-code-hud
description: "Instala e atualiza o HUD do Claude Code para Linux: CPU, RAM, load, modelo, contexto, custo e limites da sessão, mais uma linha por agente com nome, modelo próprio, tokens, ocupação do contexto e estado. Use para configurar statusline, acompanhar agentes em paralelo, instalar a barra no tmux ou corrigir dados ausentes no HUD."
metadata:
  version: "1.1.0"
---

# Claude Code HUD — 1.1.0

Barra de status que junta duas coisas normalmente separadas: **a saúde da máquina** e **o consumo da sessão do Claude Code**. Quem trabalha por SSH num servidor de produção precisa das duas ao mesmo tempo — descobrir que a RAM encheu depois que o build morreu é tarde demais, e descobrir que o limite semanal acabou no meio de uma refatoração também.

```
Opus 5 (1M context) · vendai · main · 5h 46%↻1h05  7d 61%↻17h45
█████░░░░░░░  42% ctx  $2.88  cpu 17%  ram 27.6% 8.7G/31.3G  ld 2.34
```

A versão 1.1.0 acrescenta o painel de agentes. Exemplo ilustrativo, com valores simulados:

```text
RUN Explore [a1b2c3] · claude-sonnet-4-6 · 12.4k tok · ctx 6.2% · 0m32
RUN Reviewer [d4e5f6] · claude-haiku-4-5 · 40.0k tok · ctx 20.0% · 1m10
```

O painel usa `subagentStatusLine`: uma linha para cada tarefa enviada pelo Claude Code,
com o modelo daquele agente e seus próprios dados. Não presume que todos usam o modelo
principal. Leia [references/agents.md](references/agents.md) ao instalar, personalizar
ou diagnosticar o painel. Ele usa Python 3.8+ e requer Claude Code 2.1.205+ para modelo
e tamanho de contexto. As métricas de CPU/RAM continuam sendo da máquina; custo e
limites de 5h/7 dias continuam sendo da sessão/conta. Não há custo em USD por agente
neste contrato, e esta versão não inventa esse valor.

Dois modos para o resumo principal, escolhidos automaticamente:

- **rodapé** (padrão, fora do tmux): as duas linhas acima, via `statusLine` do Claude Code
- **barra superior direita** (dentro do tmux): tudo numa linha só, no topo da tela, e o resumo principal sai do rodapé; as linhas dos agentes continuam no painel do Claude, dentro de cada pane

## Instalação

```bash
bash scripts/install.sh           # HUD + agentes + tmux + autostart no login
bash scripts/install.sh --no-autostart   # sem mexer no ~/.bashrc
bash scripts/install.sh --no-tmux        # só o rodapé
bash scripts/install.sh --dry-run        # valida e mostra o que faria
bash scripts/install.sh --no-agents      # atualiza só o HUD principal; preserva configuração de agentes existente
```

O instalador é idempotente — rodar de novo atualiza em vez de duplicar. Ele copia os três scripts Bash e o renderizador de agentes para `~/.claude/`, valida a configuração antes de copiar, faz **merge** das chaves `statusLine` e `subagentStatusLine` no `settings.json` com escrita atômica e backup exclusivo (preserva `permissions`, `hooks`, `env` e opções não alteradas pelo HUD), insere blocos delimitados por `# >>> claude-code-hud >>>` no `~/.tmux.conf` e no `~/.bashrc`, e roda a statusline **duas vezes** no fim — a primeira execução sempre mostra `cpu 0%`, porque só grava a linha de base do delta.

Confira a RAM contra `free -h` depois de instalar. Se `tmux` não existir na máquina, o instalador avisa e instala só o modo rodapé.

Para atualizar a publicação, entregue o pacote com `skill.json` em 1.1.0, mantendo
o ID, autor e licença. Preparar o pacote não instala o HUD neste computador nem
publica a versão no catálogo. Para atualizar um servidor já instalado, execute o
mesmo instalador lá e confira o painel numa sessão nova. A instalação completa
continua voltada a Linux com Bash 5 e `/proc`; o teste unitário do renderizador
pode rodar também no Windows.

## Arquitetura

O painel de agentes é independente do cache do tmux. `subagent-statusline.py`
recebe um snapshot de tarefas e devolve JSONL; não lê conversas, não registra hooks,
não consulta APIs e não mantém estado entre sessões. A lista não tem um limite
artificial no script; sua visibilidade acompanha o painel nativo do Claude Code.

Três arquivos Bash para o resumo principal, porque o tmux não tem como obter os dados da sessão sozinho — eles só existem no JSON que o Claude Code entrega pelo stdin da statusline:

| arquivo | papel |
|---|---|
| `~/.claude/hud-metrics.sh` | lib compartilhada: CPU, RAM e load de `/proc` |
| `~/.claude/statusline.sh` | parseia o JSON, grava o cache da sessão, desenha o rodapé |
| `~/.claude/tmux-hud.sh` | lê o cache + métricas e monta a linha do tmux |
| `~/.claude/subagent-statusline.py` | formata modelo e uso de cada agente no painel nativo |
| `scripts/configure.py` | valida/mescla as duas configurações durante a instalação |

A statusline grava `$XDG_RUNTIME_DIR/claude-hud-session.$UID` (escrita atômica via `.tmp` + `mv`, porque o tmux lê o arquivo a cada 2s e não pode pegar meia linha). Se esse cache passar de 20s sem atualização, o tmux mostra `claude off` e só a saúde do servidor, em vez de exibir um custo e um contexto mentirosos de uma sessão encerrada.

Cada consumidor usa seu **próprio** arquivo de cache de CPU. Se os dois compartilhassem, um consumiria a amostra anterior do outro e ambos mostrariam deltas errados.

## Restrições de performance

O resumo Bash roda a cada 3 segundos. Nesse caminho, evite `jq`, `git`, `free`, `top`, `ps`, `awk` ou `sed` — só builtins do bash e leitura de `/proc`. Um `git` por refresh trava visivelmente uma sessão SSH.

O novo painel faz uma única execução Python por snapshot, com biblioteca padrão,
sem subprocessos ou I/O externo. JSON aninhado dos agentes é processado com `json`,
não por regex. Descrições e esforço cedem lugar ao modelo e uso em telas estreitas.

Características mantidas no resumo Bash:

- **JSON** por regex do bash (`[[ $var =~ re ]]` + `BASH_REMATCH`), não por parser
- **branch** lido de `.git/HEAD` subindo os diretórios, tratando HEAD destacado (SHA curto) e `.git` como arquivo (worktree/submódulo)
- **custo e percentuais** formatados com `printf`, que é builtin
- **hora atual** via `printf '%(%s)T' -1`, não `date`

## Os pontos não óbvios

**CPU precisa de duas amostras.** `/proc/stat` traz contadores acumulados desde o boot, então uma leitura isolada não informa nada. A amostra anterior (total, idle e último %) vai para um cache em `${XDG_RUNTIME_DIR:-/tmp}` e o valor sai do delta entre duas execuções. Nada de `sleep` para amostrar — isso travaria a barra. Quando `delta_total <= 0` (duas execuções no mesmo jiffy) reusa-se o último valor, senão ocorre divisão por zero. E `idle` tem que somar `idle + iowait`.

**RAM usa `MemAvailable`, não `MemFree`.** `MemFree` ignora cache e buffers recuperáveis e reporta pressão de memória falsa — num servidor com 20 GB em `buff/cache` ele acusaria quase tudo ocupado. Há fallback para `MemFree` se o kernel for antigo demais para ter `MemAvailable`.

**`used_percentage` não é chave única no payload.** Ela aparece em `context_window` **e** nos dois blocos de `rate_limits`. Um regex solto pega o valor errado quando a ordem do JSON muda. O parser legado fatia a string com expansão de parâmetro (`${input%%'"rate_limits"'*}`), que é builtin, e aplica o regex em cada pedaço. Isso ainda depende da ordem relativa desses blocos; a atualização 1.1.0 mantém esse parser do resumo principal. Não o reutilize para arrays de agentes.

**Arredondamento ao converter MiB para "3.2G":** some 512 antes de dividir por 1024. Truncando, 3276 MiB vira 3.1G.

**A RAM mostra uma casa decimal** porque 1% de 32 GB são ~320 MB: com inteiro, um servidor estável parece congelado em `28%` o dia inteiro. O **limiar de cor usa o inteiro truncado**, não arredondado — se arredondasse, 59.6% viraria amarelo enquanto o número na tela ainda diz 59.6, e limiar e número exibido discordariam.

**`refreshInterval` é obrigatório** no `settings.json`. Sem ele a statusline só roda em eventos da conversa, e CPU/RAM ficam congelados entre mensagens.

## Cores

Verde até 59%, amarelo de 60 a 84%, vermelho de 85% em diante — aplicado a contexto, CPU, RAM e aos limites de 5h/7d. Rótulos em dim. No rodapé são códigos ANSI; na barra do tmux é a marcação `#[fg=...]`, porque o `status-right` não interpreta ANSI cru.

## Autostart do tmux

O bloco no `~/.bashrc` roda `tmux new-session -A -s main` (attach-or-create: sempre a mesma sessão, sem acumular uma por login). As guardas importam mais que o comando:

| guarda | por quê |
|---|---|
| `[ -z "$CLAUDECODE" ]` | o Claude Code abre shells para rodar comandos; sem isso, **cada comando tentaria abrir um tmux** |
| `case "$-" in *i*)` | shells não interativos (scp, rsync, git over ssh) não podem ser sequestrados |
| `[ -t 1 ]` | precisa de terminal de verdade |
| `[ -z "$TMUX" ]`, `$TERM` não é `screen*`/`tmux*` | evita tmux dentro de tmux |
| `[ -z "$NO_TMUX" ]` | saída de emergência |
| `&& exit` em vez de `exec` | se o tmux falhar, cai num shell normal em vez de derrubar a conexão |

Saídas de emergência, se o tmux quebrar: `NO_TMUX=1 ssh host` ou `ssh host bash` (não interativo, nem lê o bloco).

## Problemas comuns

**"Configurei mas continua no rodapé."** Quase sempre o shell é anterior à instalação: o `.bashrc` é lido uma única vez, quando o shell nasce. Reiniciar o `claude` dentro do mesmo shell SSH antigo não relê nada. Confirme com `tmux list-sessions` e compare os horários:

```bash
ps -o pid,lstart,cmd -p $PPID          # quando o shell nasceu
ls -l --time-style=+%H:%M:%S ~/.bashrc # quando o bloco foi escrito
```

Se o shell for mais velho, `exec bash -l` resolve na hora, ou basta o próximo login.

**"A RAM está travada num valor."** Antes de caçar bug, cheque a escala: 1% de 32 GB são ~320 MB, e um servidor estável não se move tanto. Para provar que o HUD reage, aloque memória de verdade e observe:

```bash
head -c 3G /dev/zero > /dev/shm/hud-ramtest   # +3 GB reais
rm -f /dev/shm/hud-ramtest                    # libera
```

**"Os agentes não aparecem / mostram --."** Confira a versão do Claude Code e a
configuração efetiva de `subagentStatusLine`. Modelo e contexto podem ainda não
estar disponíveis no início. O script mantém `--` até receber dados. Amplie o
painel nativo se o cliente o recolheu. Veja [references/agents.md](references/agents.md).

**"O CPU aparece 0%."** Normal na primeira execução — ela só grava a linha de base. Rode de novo.

**"A barra do tmux não aparece / não mudou."** O `~/.tmux.conf` só é lido quando o servidor tmux sobe. Com um tmux já rodando, use `tmux source-file ~/.tmux.conf`, que recarrega a configuração sem encerrar as sessões.

**"O `#()` do tmux volta vazio."** Ele roda assíncrono: a primeira expansão vem vazia e preenche em seguida. Para testar de verdade, rode o tmux dentro de outro tmux e capture a tela:

```bash
tmux new-session -d -s inner
tmux new-session -d -s outer -x 150 -y 18
tmux send-keys -t outer 'TMUX= tmux attach -t inner' Enter
sleep 5; tmux capture-pane -p -t outer | head -2   # a 1a linha e a barra
```

## Customização

Forçar o modo, em vez do automático: escreva `tmux` ou `inline` em `~/.claude/hud-mode` (o padrão é `auto`, que decide pela presença de `$TMUX`).

Para mudar o que aparece, edite a montagem de `line1`/`line2` em `statusline.sh` (rodapé) ou de `out` em `tmux-hud.sh` (barra). Os campos disponíveis no payload estão em `references/payload.md` — vale ler antes de inventar um nome de chave, porque vários campos úteis (cache de prompt, `exceeds_200k_tokens`, `effort`) não são óbvios.

Para descobrir o payload de uma versão nova do Claude Code, capture o que chega de fato:

```bash
# no topo do statusline.sh, logo depois de input=$(cat)
printf '%s\n' "$input" > /tmp/payload.json
```

Deixe rodar um refresh, leia o arquivo e **remova a linha depois** — ela escreve em disco a cada 3 segundos.

Requisitos

• Acesso a terminal com bash 5 e leitura de /proc (Linux)
• Python 3.8+ para a instalacao e renderizacao dos agentes
• Claude Code 2.1.205+ para modelo/contexto dos agentes (effort: 2.1.214+)
• tmux opcional para o resumo no topo

Permissões declaradas

• Escreve em ~/.claude/ (scripts e settings.json)
• Acrescenta blocos delimitados em ~/.tmux.conf e ~/.bashrc
• Le /proc/stat, /proc/meminfo e /proc/loadavg
• Recebe JSON de statusLine e subagentStatusLine pelo stdin; nao le transcripts nem usa rede

Versões

• v1.1.0

  Adiciona painel nativo de agentes com nome/ID, modelo resolvido individualmente, tokens, percentual de contexto, estado, tempo em execucao e effort quando informado. Renderizacao adaptavel a largura, sem cache compartilhado ou varredura de transcripts. Instalador mescla statusLine/subagentStatusLine com escrita atomica, backup unico e validacao previa; opcao --no-agents. Mantem resumo Linux/tmux da versao anterior. Testes offline incluidos; integracao em servidor real pendente.

• v1.0.0

  Primeira publicacao. HUD de statusline com saude do servidor (CPU por delta de /proc/stat, RAM via MemAvailable com uma casa decimal, load) e consumo da sessao (modelo, diretorio, branch, contexto, custo, limites de 5h e 7 dias). Dois modos automaticos: rodape do Claude Code e barra superior do tmux. Instalador idempotente com --dry-run, --no-tmux e --no-autostart.