Quando você assume um repositório — ou acabou de clonar algo novo — a primeira coisa que faz é digitar o encantamento familiar: instalar dependências, compilar, rodar testes, subir o servidor, checar a porta. Cada projeto precisa da sua própria variante: npm para alguns, pip para outros, cargo build aqui, docker compose up acolá.

O hermes verify, que chegou à main do Hermes Agent no início de agosto de 2026, foi feito exatamente para esse momento: um comando que responde “este projeto realmente roda?” Ele detecta automaticamente a recipe de execução do projeto e faz uma passada completa de smoke test na ordem bootstrap → build → test → start → readiness, e então retorna um veredito estruturado.

$ hermes verify
detected: node (npm, vite)
bootstrap ✓  build ✓  test ✓
start on :5173 → ready in 2.1s
VERIFY PASS · evidence recorded

---

1. O que ele faz

O fluxo de trabalho central do hermes verify:

1. Detect — examina o diretório atual (ou um caminho informado) em busca de arquivos de assinatura, descobre qual framework o projeto usa e monta uma recipe;
2. bootstrap — instala/prepara as dependências (ex.: make install ou o alvo de instalação detectado);
3. build — compila o projeto (npm run build, go build ./..., cargo build, mvn package, …);
4. test — roda a suíte de testes (npm test, pytest, go test ./..., mvn test, …);
5. start — inicia o app em segundo plano e faz o poll de readiness (timeout de readiness de 60s por padrão, porta sobrescrevível);
6. teardown — limpa tudo, imprime um resumo de evidências e um veredito estruturado de passou/falhou.

Se ele não reconhece o projeto, diz isso explicitamente e mostra como definir uma recipe manualmente.

Como ele se encaixa no que o Hermes já tem

O Hermes já tinha três camadas de verificação (auto-verificação, contratos de conclusão, comandos de teste canônicos). O hermes verify preenche a lacuna que elas deixavam: verificação de smoke test em tempo de execução — o projeto realmente compila, realmente sobe, e a porta realmente responde? Execuções bem-sucedidas são registradas no livro de evidências de verificação (agent/verification_evidence), compartilhando o mesmo armazenamento de evidências que a proteção verify-on-stop — um hermes verify que passa tem o mesmo peso que um comando de teste canônico que passa.

Ponto de design chave: é um comando CLI puro com zero pegada de ferramentas de modelo — nenhuma ferramenta nova visível ao modelo, nenhuma mudança na superfície de ferramentas do agente.

2. Tipos de projeto suportados

Os detectores reais em agent/verify/recipes.py (cada um com strings de evidência):

Project	Signature	Default build / test / start
Node.js	package.json + package manager (npm/pnpm/yarn)	npm run build / npm test / npm run dev (vite & friends)
Python (Django)	manage.py or django dep	— / python manage.py test / python manage.py runserver 0.0.0.0:8000
Python (FastAPI etc.)	pyproject/requirements	— / pytest (or unittest) / per detection
Go	go.mod	go build ./... / go test ./... / go run .
Rust	Cargo.toml	cargo build / cargo test / cargo run
Java (Maven)	pom.xml	mvn package / mvn test
Java (Gradle)	build.gradle(.kts)	./gradlew build / ./gradlew test
Makefile project	Makefile	auto-picks install/build/test/run targets
docker-compose	compose.yml etc.	docker compose build / docker compose up

3. Flags completas

hermes verify [path] [options]

  path               project root to verify (default: current directory)

  --detect-only      detect and print the recipe as JSON only; run nothing
  --save             save the recipe as .hermes/environment.json in the project
  --skip-start       run command phases but skip booting the app / readiness poll
  --phase <name>     run only the given phase(s) (bootstrap|build|test|start; repeatable)
  --port <n>         override the port used for the readiness poll
  --timeout <sec>    per-phase timeout (default 600s)
  --ready-timeout <sec>  readiness poll timeout (default 60s)
  --json             emit a machine-readable JSON result

4. Uso típico

Checagem de smoke test do dia a dia

cd ~/projects/acme-web
hermes verify

Somente detecção — veja se ele reconhece seu projeto

hermes verify --detect-only
# {"source": "detected", "recipe": {"kind": "node", ...}}

Fixar a recipe

A detecção pode derivar conforme o conteúdo do diretório muda. O --save congela a recipe em .hermes/environment.json; depois disso, o hermes verify carrega esse manifesto primeiro e os resultados ficam reproduzíveis:

hermes verify --save
# Saved manifest: /Users/me/projects/acme-web/.hermes/environment.json

Saída JSON como gate de CI

hermes verify --json
# {"ok": true, "recipe": {...}, "phases": {...}}

Somente a fase de teste

hermes verify --phase test

5. Definindo uma recipe manualmente

Quando o --detect-only falha, a mensagem aponta para criar .hermes/environment.json no projeto para definir a recipe à mão. O manifesto é escopado ao projeto, e se o .hermes/ entra no .gitignore é decisão sua — mas note que ele tem precedência sobre a auto-detecção, então, uma vez salvo, todas as verificações futuras seguem a sua definição.

6. Trade-offs de design que valem nota

• Zero pegada de modelo: verify é um comando CLI, não uma ferramenta do agente — ele atende “um humano no terminal confirmando rapidamente a saúde do projeto” e não custa nada do orçamento de ferramentas do agente;
• Evidências são registradas: execuções bem-sucedidas entram no livro de evidências de verificação, compartilhado com a proteção verify-on-stop, fechando o ciclo;
• Falha rápido: timeout de 600s por fase e 60s de readiness por padrão — um projeto travado nunca fica pendurado para sempre.

Resumo

O hermes verify automatiza o ritual cotidiano de “clonar e fazer rodar”: detectar o framework, instalar, compilar, testar, subir, sondar — um comando, veredito estruturado. É especialmente útil se você avalia repositórios desconhecidos com frequência ou quer um gate de smoke barato no CI.

Mais do nosso site: combine-o com o nosso guia completo de automação de cron do Hermes Agent para rodar o verify em uma agenda, leia como o Hermes lida com erros e se recupera, ou instale o Hermes em cinco minutos.