lokkju/term-recorder

O que term-recorder faz?

O term-recorder executa um comando em um terminal de tamanho fixo, controla-o com passos e captura o que ele exibe. Use-o quando a pergunta for "como isso se parece na tela", algo que a leitura do código não pode responder: como um diálogo quebra texto longo, se o markdown é renderizado, o que uma TUI faz em 100 colunas, onde um clique cai.

Ele executa o comando em seu próprio servidor tmux (tmux -L term-record-<pid>, uma configuração gerada, sem linha de status) com um ambiente mínimo, de modo que nunca toca nas sessões tmux do usuário e o comando não herda as variáveis desta sessão. O servidor é encerrado quando a execução termina.

Executando

Chame a ferramenta record (a do servidor MCP term-recorder; no Claude Code mcp__plugin_term-recorder_term-recorder__record) com:

• command: o programa e seus argumentos como uma lista, por exemplo ["claude", "--model", "haiku"].
• steps: os passos inline, um por linha (abaixo), ou steps_file para um arquivo de passos; ambos executam o arquivo primeiro. ${EXAMPLES} nos passos é o diretório de exemplos incluído.
• cwd: onde o comando inicia (padrão: o diretório do projeto). Os caminhos de include e paste em passos inline são relativos a ele.
• out: para onde as capturas vão (padrão: um novo diretório temporário); o diretório é criado.

Cada snap NAME escreve <out>/NAME.txt, e a tela é sempre capturada como final ao final. O resultado é a tela de cada captura como texto, depois onde as capturas foram salvas; leia-os, eles são a resposta. show: "final" retorna apenas a tela final e show: "none" nenhuma (os arquivos são escritos de qualquer forma); a ferramenta snaps lista as capturas de uma execução anterior ou lê uma pelo nome. Um passo com falha (um tempo de espera expirou, o texto para clicar não estava na tela, o comando encerrou) faz com que o resultado seja um erro que nomeia o passo e mostra a tela naquele momento.

check_steps analisa os passos sem executar nada, o que é um seguro barato antes de uma execução que custa uma conversa real com o Claude Code.

Os padrões: 100x30 (size), TERM screen-256color, e apenas HOME, PATH, USER, LOGNAME, SHELL, LANG, LC_ALL, LC_CTYPE e TMPDIR do ambiente do servidor. Adicione variáveis com env (um objeto) ou pass (nomes), e substituições em passos com vars.

Sem o servidor MCP

Em um agente sem o servidor, execute a CLI sobre o mesmo código. Escreva os passos em um arquivo no seu diretório de rascunho e então execute-o como seu próprio comando, não encadeado a outro:

"${CLAUDE_SKILL_DIR}/scripts/term-record" -C <workdir> -s <passos> -o <outdir> -- <comando> [args...]

${CLAUDE_SKILL_DIR} é o diretório que contém este SKILL.md. O Claude Code o preenche automaticamente; em um agente que o deixa como está, coloque o caminho desse diretório em seu lugar. As capturas são impressas no stdout além de irem para <outdir>. O status de saída 1 significa que um passo falhou, com a tela no stderr; 2 é um problema de uso ou configuração. As flags correspondem aos argumentos da ferramenta: --size, --env NOME=VALOR, --pass NOME, --var NOME=VALOR, --cast, --gif, --agg-arg, e -s - lê passos da entrada padrão.

Passos

Um por linha, aspas de shell, comentários #:

Passo	Faz
wait REGEX [TIMEOUT]	espera até que a tela corresponda (Python re, multilinha; 90s)
gone REGEX [TIMEOUT]	espera até que não corresponda mais
idle REGEX [QUIET] [TIMEOUT]	espera até que REGEX, um marcador de ocupado, esteja ausente por QUIET segundos (3; 240s)
keys TECLA...	envia nomes de tecla do tmux: Enter, Down, Escape, C-c
type TEXTO [ATRASO]	digita TEXTO literalmente, um caractere a cada ATRASO segundos (0.03; 0 envia de uma vez)
paste ARQUIVO	cola ARQUIVO como uma única colagem entre colchetes, adequada para prompts de várias linhas
click TEXTO	clica com o botão esquerdo no primeiro TEXTO na tela
sleep SEGUNDOS
snap NOME	captura a tela como texto
resize COLxLIN	altera o tamanho do terminal durante a execução; capture após cada um para ver onde um layout quebra
record on|off	liga ou desliga os quadros da gravação
include ARQUIVO	executa os passos de ARQUIVO no lugar
when REGEX PASSO...	executa PASSO apenas se a tela corresponder agora

Os caminhos em include e paste são relativos ao arquivo de passos (para cwd em passos inline).

Claude Code como alvo

include ${EXAMPLES}/claude-start.steps inicia uma nova sessão passando pelo diálogo de confiança da pasta até um prompt vazio; coloque-o primeiro. ${EXAMPLES}/ask-dialog.steps é um exemplo completo que abre o diálogo de pergunta e o captura.

• Inicie-o em um diretório de rascunho (cwd), com um modelo barato (--model haiku) a menos que o modelo importe, e DISABLE_AUTOUPDATER=1 em env para que nenhum aviso de atualização apareça no quadro.
• Para testar um plugin a partir de um checkout, adicione --plugin-dir <caminho> e passe --settings <arquivo> para desligar a cópia instalada ("enabledPlugins": {"<nome>@<marketplace>": false}).
• As ferramentas de tarefa (TaskCreate e as demais) estão desligadas nos modelos Claude 5, interativo ou -p, a menos que CLAUDE_CODE_ENABLE_TODO_TOOLS=1 esteja em env. Desde Claude Code 2.1.300, --model haiku é Haiku 5.5, então isso inclui haiku. Mesmo assim, são ferramentas diferidas: aparecem na lista de ferramentas diferidas e carregam via ToolSearch, não na lista inicial de ferramentas.
• Seu prompt é ecoado na tela, então espere apenas por texto que o resultado mostra (uma opção numerada de diálogo como '[0-9]\. Accept'), nunca por uma palavra do próprio prompt.
• Seu marcador de ocupado, para idle: '\([0-9]+m? ?[0-9]*s · |esc to interrupt'.
• Cada execução é uma conversa real na conta do usuário. Mantenha-a nos turnos que a verificação precisa.

Gravações

cast escreve um arquivo asciicast v2, e gif renderiza um através do agg (agg_args substitui seus argumentos); o resultado fornece ambos os caminhos. Os quadros são capturados quando a tela muda; durante uma espera idle o relógio da gravação corre oito vezes mais devagar (busy_timescale), então um minuto de pensamento é reproduzido em alguns segundos.