.agent/TOOLS.md

Ferramentas Recomendadas para Otimização de IAs no Desenvolvimento

Este documento lista ferramentas de linha de comando (CLI) e utilitários que otimizam significativamente o trabalho e a integração de Agentes de IA durante o processo de desenvolvimento. Todas as ferramentas listadas possuem suporte nativo para Linux e macOS.

1. Busca e Navegação de Código

ripgrep (rg)

• Descrição: Uma ferramenta de busca orientada a linhas que busca recursivamente no diretório atual por uma expressão regular.
• Por que ajuda as IAs: É extremamente rápida para encontrar referências de código, funções e variáveis em repositórios grandes. Ajuda as IAs a varrer bases de código rapidamente sem precisar ler todos os arquivos.
• Instalação:
  • Mac: brew install ripgrep
  • Linux (Ubuntu/Debian): sudo apt-get install ripgrep

fd

• Descrição: Uma alternativa simples, rápida e amigável ao comando find.
• Por que ajuda as IAs: Permite que as IAs listem a estrutura de arquivos e localizem caminhos específicos com uma sintaxe muito mais amigável e saída mais rápida e limpa que o find tradicional, respeitando o .gitignore nativamente.
• Instalação:
  • Mac: brew install fd
  • Linux (Ubuntu/Debian): sudo apt-get install fd-find

ast-grep (sg)

• Descrição: Uma ferramenta de busca e substituição de código baseada em Árvore de Sintaxe Abstrata (AST).
• Por que ajuda as IAs: Diferente do regex padrão, permite que a IA faça buscas estruturais e refatorações complexas compreendendo a semântica da linguagem.
• Instalação:
  • Mac/Linux: npm install -g @ast-grep/cli ou brew install ast-grep

2. Processamento de Dados

jq

• Descrição: Um processador JSON de linha de comando leve e flexível.
• Por que ajuda as IAs: Sistemas baseados em agentes interagem frequentemente por payloads JSON e chamadas de API. O jq é a ferramenta perfeita para que a IA filtre, extraia e transforme grandes payloads de dados diretamente no terminal.
• Instalação:
  • Mac: brew install jq
  • Linux (Ubuntu/Debian): sudo apt-get install jq

yq

• Descrição: Uma extensão leve e portável do jq voltada para o processamento de arquivos YAML, JSON e XML.
• Por que ajuda as IAs: Útil para a IA inspecionar, modificar e gerar configurações como docker-compose.yml, esquemas de CI/CD, e manifestos Kubernetes.
• Instalação:
  • Mac: brew install yq
  • Linux: O binário é baixado direto da distribuição oficial no Github ou via snap.

3. Qualidade de Código e Formatação

Biome

• Descrição: Ferramenta All-in-One super rápida para formatação e linting de projetos Web (JavaScript, TypeScript, JSX, JSON).
• Por que ajuda as IAs: Como exigido pelos padrões do projeto, garante que o código escrito pela IA passe pela validação, sendo auto-focado e sem configurações complexas (biome check --write).
• Instalação:
  • Mac/Linux: npm install -g @biomejs/biome ou gerenciamento local (pnpm add -D @biomejs/biome).

ShellCheck

• Descrição: Ferramenta de análise estática e linting projetada especificamente para scripts de shell (bash/sh).
• Por que ajuda as IAs: Assegura que scripts bash gerados por IAs (seja para deploy ou testes de automação de fluxo) sigam as melhores práticas e não tenham comandos perigosos implícitos.
• Instalação:
  • Mac: brew install shellcheck
  • Linux (Ubuntu/Debian): sudo apt-get install shellcheck

4. Visualização e Visualização de Texto

bat

• Descrição: Um clone do cat com suporte nativo a syntax highlighting (destaque de sintaxe) e integração com o Git.
• Por que ajuda as IAs: Ao extrair ou ler recortes de arquivos e logs, o conteúdo é formatado de maneira que facilita eventuais inspeções humanas e recortes por linhas (bat -r <linha_inicio>:<linha_fim>).
• Instalação:
  • Mac: brew install bat
  • Linux (Ubuntu/Debian): sudo apt-get install bat

tree / eza

• Descrição: Utilitários para listar o conteúdo de diretórios. O eza é um substituto moderno para o ls com suporte de árvore.
• Por que ajuda as IAs: Permitir que agentes mapeiem mentalmente a árvore de projeto de forma clara. Essencial para IAs auto-localizarem módulos arquiteturais.
• Instalação:
  • Mac: brew install eza tree
  • Linux (Ubuntu/Debian): sudo apt-get install tree eza

5. Integração com APIs e Git

HTTPie / cURL

• Descrição: Ferramenta gráfica ou cli para o teste de endpoints, sendo o HTTPie uma versão "humanizada" do cURL.
• Por que ajuda as IAs: Auxilia nas IAs de codificação que necessitam conferir os status e formatos dos endpoints REST antes de gerar lógicas assíncronas no front-end ou back-end.
• Instalação (HTTPie):
  • Mac: brew install httpie
  • Linux: sudo apt-get install httpie

GitHub CLI (gh)

• Descrição: Interface de linha de comando nativa para interagir com repositórios no GitHub.
• Por que ajuda as IAs: Permite à IA criar pull requests, listar issues e manipular webhooks diretamente do terminal como parte de fluxos autonomos de entrega contínua.
• Instalação:
  • Mac: brew install gh
  • Linux: sudo apt install gh

---

6. Automação e Testes de Interface (Browser)

agent-browser

• Descrição: CLI de automação de navegadores baseada em Rust, projetada especificamente para Agentes de IA.
• Por que ajuda as IAs: Utiliza representação compacta da árvore de acessibilidade com referências determinísticas (@e1, @e2), consumindo 200–400 tokens (até 90% menos tokens que a leitura do DOM completo). Permite executar testes E2E, interagir com telas, validar fluxos e registrar evidências visuais.
• Modo Visível Obrigatório: Para que o operador acompanhe cada teste em tempo real na tela, execute sempre com a flag --headed (ex: agent-browser --session <modulo>_<contexto?> open --headed <url>) ou defina export AGENT_BROWSER_HEADED=true.
• Isolamento Mandatório de Sessão e Contexto: Toda execução DEVE acompanhar a flag --session <modulo>_<contexto?> (onde <modulo> é o modulo-id extraído de memorias-ia/modulo.yml e <contexto?> discrimina acessos como interno, externo, cliente, anonimo) ou garantir export AGENT_BROWSER_SESSION=<modulo>_<contexto?>. Previne fechamento indevido de processos e contaminação cruzada de cookies e tokens JWT entre diferentes perfis de usuário.
• Pasta Obrigatória de Evidências (.evidencias/): Todas as evidências geradas pelos testes automatizados (screenshots, capturas anotadas, vídeos, traces, relatórios) devem ser salvas obrigatoriamente na pasta .evidencias/ na raiz do projeto (mkdir -p .evidencias).
• Instalação:
  • Com Bun (padrão): bun i -g agent-browser && agent-browser install
  • Com NPM: npm install -g agent-browser && agent-browser install
• Documentação: https://agent-browser.dev/

---

7. Utilitários Nativos do Framework .agent

atualizar-submodulo.sh (.agent/scripts/atualizar-submodulo.sh)

• Descrição: Script de ciclo de vida acionado automaticamente via hook PreInvocation (.agent/hooks.json) ou manualmente via CLI.
• Por que ajuda as IAs e Operadores: Garante que o submódulo .agent esteja sincronizado na branch master remota no início de cada sessão de conversa (1x por sessão) e verifica automaticamente uma vez por dia se o runtime Bun está atualizado na versão estável mais recente executando bun upgrade --stable (controlado via trava diária /tmp/.antigravity_bun_upgrade_date).
• Uso: bash .agent/scripts/atualizar-submodulo.sh

notificar.sh (.agent/notificar.sh)

• Descrição: Utilitário unificado de notificação para o Sistema Operacional, compatível nativamente com Linux e macOS.
• Por que ajuda as IAs e Operadores: Permite que comandos de longa duração (como /plano.executar todos e loops /goal) avisem o operador imediatamente no momento da conclusão, emitindo popup no desktop (KDE kdialog, FreeDesktop notify-send / gdbus, macOS Notification Center via osascript), som de alerta discreto (PipeWire, PulseAudio ou macOS afplay) e campainha no terminal (\a). Totalmente assíncrono, não-bloqueante e seguro para ambientes headless.
• Uso: sh .agent/notificar.sh "<Título>" "<Mensagem>" [sucesso|aviso|erro]

upload-paiol-wiki.sh (.agent/scripts/upload-paiol-wiki.sh)

• Descrição: Utilitário de linha de comando para upload de arquivos e mídias da Wiki para o bucket público wiki no MinIO Paiol (https://paiol.idz.one/wiki/...).
• Por que ajuda as IAs e Operadores: Previne o inchaço (bloat) do Git da Wiki desacoplando binários pesados (PDFs, imagens em alta resolução, vídeos, capturas de tela e anexos), gerando links e snippets Markdown prontos para inclusão imediata na documentação.
• Uso: sh .agent/scripts/upload-paiol-wiki.sh <caminho-do-arquivo> <slug-funcionalidade-ou-pagina> [modulo-override]

graphify.sh (.agent/scripts/graphify.sh)

• Descrição: Utilitário canônico de Grafo de Conhecimento (Knowledge Graph) do código-fonte baseado em @sentropic/graphify.
• Por que ajuda as IAs: Permite que o comando /plano e os agentes localizem símbolos, mapeiem dependências entre pacotes e calculem o raio de impacto em cascata (Blast Radius) em segundos sem varreduras cegas. Instala automaticamente o binário via Bun (bun i -g @sentropic/graphify) caso não exista na máquina, atualiza o .gitignore (.graphify/, .engram/, graphify-out/) e gera o grafo sob demanda (ensure).
• Uso:
  • bash .agent/scripts/graphify.sh update (reconstrói/atualiza o grafo AST)
  • bash .agent/scripts/graphify.sh ensure (garante instalação, .gitignore e grafo existente)
  • bash .agent/scripts/graphify.sh query "<termo>" [budget] (busca nós e arquivos no grafo)
  • bash .agent/scripts/graphify.sh explain "<simbolo-ou-arquivo>" (detalha conexões e imports)
  • bash .agent/scripts/graphify.sh impact <arq1> [arq2...] (calcula raio de impacto e lacunas de testes via review-delta)
  • bash .agent/scripts/graphify.sh summary (exibe principais hubs e comunidades do projeto)

---

8. Instalação Rápida (Copia e Cola)

Para instalar as ferramentas base de forma ágil e em lote, copie os blocos de comando abaixo e os rode inteiramente em seu terminal (requer npm, bun e snap já configurados).

Linux (Debian / Ubuntu)

# 1. Atualizar e instalar ferramentas base do sistema
sudo apt-get update
sudo apt-get install -y ripgrep fd-find jq shellcheck bat tree eza httpie gh

# 2. Instalar ferramentas em Node
npm install -g @ast-grep/cli @biomejs/biome

# 3. Instalar automação de navegador e Grafo de Conhecimento para IA via Bun
bun i -g agent-browser @sentropic/graphify && agent-browser install

# 4. Instalar yq via snap 
sudo snap install yq

macOS (via Homebrew)

# Instalar utilitários essenciais
brew install ripgrep fd ast-grep jq yq shellcheck bat tree eza httpie gh
npm install -g @biomejs/biome
bun i -g agent-browser @sentropic/graphify && agent-browser install