Codex HUD

Instruções da skill

---
name: codex-hud
description: "Instala e mantém um HUD local para o OpenAI Codex com CPU, RAM, modelo, branch, tokens, contexto aproximado, limites da conta e agentes da sessão. Use para acompanhar agentes trabalhando, ver consumo no Codex, configurar a barra nativa do CLI ou abrir um painel de monitoramento no navegador, terminal ou tmux."
metadata:
  version: "1.0.0"
---

# Codex HUD

Monitore uma sessão do Codex e seus descendentes por dados locais. O pacote inclui
um painel no navegador, uma visão de terminal, saída compacta para tmux e instalação
opcional dos itens suportados pela barra nativa do Codex CLI.

## Escolher o modo

- **Codex desktop:** use o painel HTTP local e abra a URL produzida em um painel do
  aplicativo ou no navegador. A skill não injeta uma barra no rodapé do desktop.
- **Codex CLI:** combine a barra nativa com `watch` em outro terminal para ver
  todos os agentes e recursos da máquina.
- **Linux/tmux:** use o painel em um pane ou conecte o resumo compacto a
  `status-right`, conforme [references/tmux.md](references/tmux.md).

Requisitos: Python 3.11+ e arquivos de sessão JSONL locais do Codex. Windows e Linux
têm CPU/RAM; load é disponibilizado no Linux. macOS não tem coletor de CPU/RAM
nesta versão. Não instale dependências ou altere políticas de acesso para preencher
uma métrica ausente.

## Usar a skill

1. Identifique a sessão solicitada. Use o ID da tarefa atual quando disponível;
   não confunda o ID do turno com o ID da sessão. Informe `--session-id` nos exemplos
   abaixo. Sem esse parâmetro, o coletor fixa a sessão principal mais recentemente
   modificada e informa o ID escolhido; confira se é a desejada.
2. Execute `once --json` para verificar a fonte. Ela deve corresponder ao modelo,
   diretório e ID esperados. Modelo desconhecido permanece `--`.
3. Abra `serve` para o painel ou `watch` para o terminal. No Windows, use o Python
   disponível no ambiente; não presuma que o alias da Microsoft Store funciona.
4. Valide a atualização dos dados e informe quais campos não puderam ser obtidos.
   Ao terminar um teste temporário, encerre somente o coletor que você iniciou.
   Mantenha-o ativo quando o usuário pedir o HUD em funcionamento.

```bash
python3 scripts/hud.py once --session-id ID_DA_SESSAO --json
python3 scripts/hud.py serve --session-id ID_DA_SESSAO
python3 scripts/hud.py watch --session-id ID_DA_SESSAO
```

`serve` imprime uma URL `http://127.0.0.1:PORTA/CHAVE/`. Abra essa URL exatamente;
as rotas sem a chave não expõem o painel. Não compartilhe a URL ou troque o bind
local por um endereço público. A página mostra dados privados de uso/diretório.
O coletor não lê `auth.json`, não usa credenciais e não realiza chamadas ao modelo.

Atualização padrão: 3 segundos (`--interval`). O custo desta coleta é processamento
local, sem chamadas de inferência. O navegador não depende de fontes/CDNs externos.

## O que é mostrado

| Informação | Origem / significado |
|---|---|
| Modelo e esforço | Último contexto próprio registrado para cada agente |
| CPU, RAM, load | Máquina local; não representa o servidor de inferência nem uso por agente |
| Diretório e branch | Sessão e leitura de `.git/HEAD`; suporta worktree relativo |
| Entrada, cache, saída, raciocínio, total | Contadores registrados por tarefa; cache é parte da entrada, raciocínio é parte da saída |
| Contexto aproximado | Tokens da última resposta / janela informada; pode divergir do cálculo interno do CLI |
| 5h, 7d e renovação | Snapshot de limites compartilhados da conta, quando registrado |
| Agentes | Árvore com vínculo explícito `parent_thread_id`, incluindo descendentes |
| Estado e duração | Eventos observados; ausência de atualização vira estado incerto, não conclusão presumida |
| USD estimado | Opcional, com preços fornecidos e verificados; nunca apresentado como cobrança real |

Consulte [references/data.md](references/data.md) antes de mudar o parser ou ativar
estimativas de preço. A semântica dos contadores e a exclusão do histórico herdado
são essenciais para não atribuir consumo do pai ao filho.

Não prometa visibilidade sobre subagentes efêmeros, arquivos de outras máquinas ou
agentes sem registro local. O painel não possui limite artificial de linhas, mas só
exibe os agentes encontrados na árvore da sessão. Não crie agentes pagos apenas para
testar o HUD sem que o trabalho em paralelo faça parte da solicitação autorizada.

## Instalar e atualizar

Para usar diretamente o pacote, não é necessário instalar. Para torná-lo descobrível
por sessões futuras, o instalador copia a skill para `$CODEX_HOME/skills/codex-hud`
ou `~/.codex/skills/codex-hud`. `--dest` permite outro destino. Criar/publicar o ZIP
não equivale a instalar ou ativar o monitor na máquina.

```bash
python3 scripts/install.py --dry-run
python3 scripts/install.py
# Opcional: também configurar a barra nativa do CLI
python3 scripts/install.py --native-status-line --dry-run
python3 scripts/install.py --native-status-line
```

A barra nativa usa `tui.status_line` em `config.toml`; não use `statusLine`,
`subagentStatusLine` ou hooks do Claude Code. O instalador preserva as demais
configurações, faz backup antes de alterar o TOML e valida o resultado por estrutura.
Em formatos TOML ambíguos, interrompe sem reescrever o arquivo; use `/statusline`
no CLI ou adapte a edição preservando a configuração existente.

Não há autostart, alteração do shell nem instalação de serviço por padrão.
Isso permite usar o HUD também no Windows e testar sem modificar o login do usuário.

## Validar e diagnosticar

```bash
python3 -m unittest discover -s tests -v
```

- **CPU `--` no primeiro snapshot:** precisa de duas amostras; use `watch`/`serve`.
- **Sem agentes:** confira o ID da sessão, `$CODEX_HOME` e o vínculo de descendência.
  Não troque por uma busca em todos os processos nem misture tarefas independentes.
- **Limites ausentes/antigos:** não são cota zero ou ilimitada. Confira `/status` ou,
  no desktop, a ferramenta de leitura de limites quando disponível. Não resgate
  créditos nem altere a conta para atualizar o painel.
- **USD indisponível:** normal sem tabela verificada e registros por resposta.
- **Modelo/uso deixou de aparecer após atualizar o Codex:** o formato JSONL é
  interno. Compare somente os campos de metadados/eventos com
  [references/data.md](references/data.md), adicione fixtures sintéticas e reteste.
  Não inclua prompts, respostas, segredos ou transcripts reais no ZIP da skill.

Base verificada: Codex CLI `0.155.0-alpha.9.2`, com dados locais de sessão e subagente.
Não trate essa verificação como garantia de compatibilidade com toda versão futura.
Fontes oficiais e limites de integração estão em [references/data.md](references/data.md).

Requisitos

• Python 3.11+
• Arquivos de sessão JSONL locais do Codex
• Windows ou Linux para CPU/RAM
• tmux opcional no Linux

Permissões declaradas

• Lê metadados e eventos dos arquivos de sessão do Codex
• Lê métricas locais e .git/HEAD
• Serve painel somente em 127.0.0.1 quando solicitado
• Instala a skill e opcionalmente atualiza tui.status_line com backup quando solicitado

Versões

• v1.0.0

  Versão inicial: painel local com agentes e métricas; leitura incremental de sessões e separação do histórico herdado; estimativa de custo opcional com preços verificados; instalador e testes incluídos. Não modifica o rodapé interno do Codex desktop.