Seu screenshot da área de transferência como entrada do Hermes: o comando hermes clipboard image

Você tirou um screenshot e quer fazer uma pergunta sobre ele: “de qual etapa vem este erro?”. Estando no terminal, o movimento natural é Ctrl+V. Esse movimento não existe dentro de um script — scripts rodam comandos, não apertam teclas. Então você escreveu três linhas de shell em volta do xclip, descobriu que elas não fazem nada no Windows, precisou de outro conjunto no macOS e acabou desistindo e salvando o arquivo na mão.
A mudança integrada em 6 de novembro leva isso para dentro do Hermes. hermes clipboard image grava a imagem da área de transferência da máquina em um arquivo: em caso de sucesso imprime o caminho e, com --json, devolve uma resposta JSON estável e um conjunto de códigos de saída distintos. Ele lê apenas a área de transferência de a máquina em que roda — sem gateway, sem session store, sem arquivo de profile.
O jeito antigo: rodar o script privado da TUI
O Hermes já cola imagens no terminal há um tempo, e a implementação em hermes_cli/clipboard.py faz bastante trabalho específico de plataforma. Mas o único ponto de entrada exposto era um script interno: ui-tui/scripts/clipboard_image.py. Um cliente de terceiros que quisesse imagens da área de transferência tinha que apontar o PYTHONPATH para a árvore de código do Hermes e chamar esse script.
Funcionava, e era frágil em três lugares ao mesmo tempo: o caminho podia mudar, os argumentos podiam mudar e até a resposta true/false dele podia mudar. O problema mais profundo era “onde fica a árvore de código?” — por que um cliente saberia onde o usuário instalou o Hermes?
O comando novo embrulha o mesmo extrator (hermes_cli.clipboard.save_clipboard_image) em um comando documentado, com códigos de saída e JSON.
Um comando, um arquivo no disco
hermes clipboard image --out /tmp/shot.png
Em caso de sucesso ele imprime o caminho. --out é criado ou sobrescrito, e o diretório dele é criado se necessário. Em scripts você quase sempre vai querer a forma JSON:
hermes clipboard image --out /tmp/shot.png --json
{"ok": true, "path": "/tmp/shot.png", "mime": "image/png", "bytes": 248193}
mime não é adivinhado pela extensão — é lido dos magic bytes do arquivo, então PNG, JPEG, GIF, BMP, TIFF e WebP são todos identificados. Normalmente a saída é sempre PNG, porque o extrator converte; a única exceção é quando você copiou um arquivo de imagem (um drop de arquivo no Windows/WSL), que é copiado byte a byte e pode ser um jpg ou um webp.
Cada desfecho tem seu próprio código de saída
Em automação o pior modo de falha não é falhar — é falhar sem dizer por quê. Este comando separa os desfechos:
| Situação | reason no JSON |
Saída |
|---|---|---|
| Uma imagem foi gravada | nenhum, ok: true |
0 |
| A área de transferência não tem imagem (só texto) | no_image |
1 |
| Nenhuma ferramenta de clipboard utilizável está instalada | no_tool, mais as ferramentas que ele procurou |
3 |
--out não pode ser gravado |
write_failed |
4 |
| Argumentos inválidos | sem JSON, erro de uso do argparse | 2 |
Manter no_image separado de no_tool importa: um significa que você não tirou um screenshot, o outro significa que esta máquina não consegue ler área de transferência nenhuma. Eles pedem correções diferentes. Rode em um servidor sem sessão gráfica e você recebe no_tool, não uma falha vaga.
Por que isso merece um comando próprio
Porque ele resolve uma questão de engenharia específica: ler a área de transferência tem que ser local.
Pense em como os gateways são implantados. O gateway do Hermes de um usuário pode rodar em uma máquina remota ou em um container, enquanto a pessoa e a área de transferência dela estão em um laptop. Se “ler a área de transferência” fosse um RPC do gateway, ele leria a área de transferência da máquina lá longe — inútil, geralmente vazia. Por isso o comando é deliberadamente local ao dispositivo: sem conexão com gateway, sem session store, sem arquivo de profile, estritamente “grave a imagem da área de transferência desta máquina neste caminho”.
A metade da escrita também é cuidadosa. Ele extrai para um diretório temporário privado ao lado do destino e renomeia o arquivo pronto para cima do --out, então em qualquer falha o arquivo existente fica exatamente como estava — nada de imagem pela metade. Sobrescrever um arquivo existente mantém os bits de permissão dele, para que um arquivo temporário 0600 não os amplie em silêncio.
Ligando ao Hermes
Uma vez que você tem um caminho, o resto é comum. O hermes chat já aceita --image, então um screenshot pode ir junto com uma pergunta:
hermes clipboard image --out /tmp/shot.png --json > /tmp/shot.json
hermes chat -q "Which stage is this error from? One conclusion and one command to check it." --image /tmp/shot.png --oneshot
Pular o arquivo intermediário é fácil com jq:
SHOT=$(hermes clipboard image --out /tmp/shot.png --json | jq -r .path) && hermes chat -q "What is misaligned in this UI?" --image "$SHOT" --oneshot
Tire o --oneshot e o hermes chat continua interativo, com a imagem anexada àquela pergunta — que é o loop do dia a dia de “screenshot, pergunta, continua a conversa”.
Os detalhes de plataforma que você vai encontrar de fato
- macOS:
pngpasteprimeiro (rápido, mais formatos), depoisosascriptcomo fallback sempre presente. - Windows:
powershellprimeiro, depoispwsh. - Linux: sob WSL ele tenta
powershell.exeprimeiro; em Wayland,wl-paste; em X11,xclip. Uma sonda WSL que falha cai para as próximas, porque o WSLg pode ainda ter umwl-pasteouxclipfuncionando. - Modo container do NixOS: todo subcomando
hermesroda dentro do container gerenciado, este incluído, então ele não vê a área de transferência do host e--outé um caminho dentro do container. Isso é uma fronteira do modo container, não um bug.
Uma coisa que isto não é: desenhar a imagem. Imagens inline no CLI e na TUI cobre como anexos e imagens produzidas por ferramentas aparecem no transcript. Este comando é a direção oposta — como uma imagem sai da área de transferência para o disco — e os dois normalmente são usados juntos.
Dá para usar hoje
O comando está no main (6 de novembro, PR #150285) e não está na tag v0.23.0. Conferir é trivial: se hermes clipboard --help imprimir alguma coisa, o seu build tem; “invalid choice” significa que não tem. Ele está documentado na seção hermes clipboard da referência do CLI, então depois que você atualizar a página bate com o que está instalado.
Atualização (10/11/2026): essas mudanças saíram na v0.23.1 (9 de novembro): basta um
hermes update. O « não está na v0.23.0 » acima continua correto; a v0.23.1 fecha a lacuna.
E se você quer saber se esta máquina consegue ler uma área de transferência, o próprio comando responde: sem imagem disponível ele distingue “sem imagem” de “sem ferramenta”, e o segundo caso lista os nomes de ferramenta que ele procurou — o que é, essencialmente, a sua lista de instalação.
A versão curta
hermes clipboard image é um comando pequeno que conserta uma fronteira de interface: promove “ler a área de transferência local” de detalhe de implementação da TUI a ponto de entrada documentado, com JSON e códigos de saída, e enuncia a regra de local-ao-dispositivo sem rodeios. Para quem scripta em cima dele, a parte mais útil não é o comando, são os quatro códigos de saída — um case agora separa “sem screenshot”, “sem ferramenta”, “não consigo gravar” e “pronto”, em vez de dar grep em texto de erro.