overreach

Overreach

Sua IA escreveu 2.000 linhas. Você tem 10 minutos para revisá-las.

Overreach mostra onde olhar primeiro. Você pediu um formulário de login — ele mostra a chave do Stripe, o endpoint de checkout e o job cron que seu agente de IA adicionou sem pedir. Determinístico, baseado em evidências, sem opiniões de IA.

Veja

$ npx -y overreach demo

  Overreach — AI PR Review
  ─────────────────────────────────────────────────
  You asked: "add a login form to the settings page"
  5 files changed · 4 in scope · 1 outside scope

  Findings

  ✗ New environment variable: STRIPE_SECRET
    .env.example
  ✗ New API endpoint: /api/checkout
    src/app/api/checkout/route.ts
  ✗ Scheduled job added
    cron.config.ts
  ⚠ File outside scope: cron.config.ts
    cron.config.ts
  ⚠ Added dependency: stripe
    package.json

  Heads Up

  → New API route added but no test file updated
  → Dependencies changed but lockfile not updated
  → 3 source files changed but no tests updated

  ─────────────────────────────────────────────────
  5 findings · review carefully · deterministic

Você pediu um formulário de login. Overreach encontrou um sistema de pagamento. Revise esses arquivos antes de fazer o merge.

Instalação

# Just run it — zero setup
cd your-project
npx -y overreach

É isso. Ele detecta automaticamente suas alterações, pergunta o que você disse à IA para fazer e mostra a revisão. Sem arquivos de configuração, sem flags para memorizar.

Ou instale permanentemente:

npm install -g overreach

# Pipe a diff with an explicit prompt
git diff | overreach --prompt "add user authentication"

# Install as a pre-commit hook
overreach init

Sem chave de API? Sem problema. Sem chave, Overreach faz parse do seu prompt com regex offline. Instantâneo, gratuito e totalmente determinístico.

Funciona com

• Claude Code
• Cursor
• Codex
• GitHub Copilot
• Windsurf
• Aider

Qualquer ferramenta que escreva código a partir de um prompt. Overreach revisa a saída, não a ferramenta.

O que ele detecta

Alterações inesperadas (coisas que a IA fez que você não pediu)

Verificação	Exemplo
Dependências	Adicionou stripe quando você pediu um formulário de login
Variáveis de ambiente	STRIPE_SECRET apareceu em .env
Endpoints de API	Rota /api/checkout que você nunca solicitou
Jobs agendados	Jobs cron ou tarefas em segundo plano adicionados silenciosamente
Listeners em tempo de execução	Servidores, handlers de WebSocket, hooks process.on
Arquivos fora do escopo	Arquivos modificados que seu prompt não mencionou
Escopo excessivo	Novas funções/classes além do que foi solicitado

Cada descoberta é determinística — derivada do seu prompt e do diff por aritmética de conjuntos. Sem opiniões de IA. Apenas: "você pediu X, o diff também contém Y, e Y não estava em X."

Atenção (coisas que você provavelmente precisa verificar)

Overreach também verifica problemas práticos entre arquivos que desenvolvedores perdem durante a revisão:

Aviso	O que detecta
Schema sem migration	Alterou schema.prisma mas não adicionou uma migration
Inconsistência de variável de ambiente	O código usa process.env.FOO mas .env não a define
Rota sem testes	Nova rota de API adicionada mas nenhum arquivo de teste atualizado
Nenhum teste	3+ arquivos de código alterados, zero arquivos de teste tocados
Dependências sem lockfile	package.json alterado mas sem package-lock.json
Auth/middleware alterado	Arquivos sensíveis à segurança modificados
Segredos hardcoded	Chaves de API ou tokens escritos diretamente no código-fonte
Arquivo grande	200+ linhas adicionadas a um arquivo — pode precisar de divisão
Arquivos novos mortos	Novo arquivo criado mas nunca importado em lugar nenhum
Dívida técnica adicionada	TODO/FIXME/HACK em 2+ arquivos
API sem documentação	Rotas de API alteradas mas documentação não atualizada
Estilos órfãos	CSS alterado mas nenhum componente atualizado
Espalhamento de configuração	3+ arquivos de configuração alterados de uma vez
Somente infraestrutura	Docker/CI alterado mas nenhum código-fonte

Isso não é escopo excessivo — são as coisas que você esquece às 2h da manhã e descobre em produção.

Por que determinístico

A maioria dos revisores de código com IA usa outra IA para julgar seu código. Isso significa opiniões, alucinações e resultados que mudam entre execuções.

Overreach não faz isso.

Ele executa um pipeline de 3 etapas:

1. Extrair escopo — Uma chamada barata de LLM lê seu prompt e extrai o que você autorizou (arquivos, dependências, variáveis de ambiente, endpoints). Ou pule o LLM completamente com o modo zero-key.

2. Analisar o diff — Extração baseada em regex. Sem LLM. Encontra cada arquivo alterado, dependência adicionada, variável de ambiente definida, endpoint criado. Executa em milissegundos.

3. Comparar — actual − authorized = findings. Aritmética pura de conjuntos. Tudo no diff que não estava no seu prompt é uma descoberta.

As etapas 2 e 3 são funções puras — mesma entrada, mesma saída, sempre. Sem inferência, sem deriva de modelo.

Gate de CI

Use Overreach como uma GitHub Action para bloquear escopo excessivo de IA em todo PR:

# .github/workflows/overreach.yml
- uses: Naveja00/Overreach@v1

Código de saída 1 quando alterações inesperadas são encontradas — o agente de IA não pode pular essa verificação.

Servidor MCP (para agentes de IA)

Agentes de IA podem usar Overreach para verificar seu próprio trabalho antes de commitar:

# Claude Code
claude mcp add overreach -- npx -y overreach --serve

# Claude Desktop / Cursor — add to MCP config:
{ "mcpServers": { "overreach": { "command": "npx", "args": ["-y", "overreach", "--serve"] } } }

Internos

Chave de API (opcional)

Overreach detecta automaticamente seu provedor de IA:

Provedor	Variável de ambiente
Anthropic	ANTHROPIC_API_KEY
OpenAI / compatível	OPENAI_API_KEY
Ollama (local)	Nenhuma chave necessária

Flags de CLI

overreach                          # Interactive mode (recommended)
overreach demo                     # Zero-key demo with sample diff
overreach init                     # Install as pre-commit hook

git diff | overreach --prompt "…"  # Pipe a diff with explicit prompt
overreach --diff file.diff --prompt "…"   # Read diff from file
overreach --scope scope.json --prompt "…" # Skip LLM, use pre-extracted scope
overreach --json                   # Machine-readable JSON output
overreach --serve                  # Start as MCP server

Saída JSON

Adicione --json para saída estruturada (CI, piping, integrações):

{
  "scope": { "files_allowed": [], "features_allowed": [] },
  "actual": { "files_changed": [], "symbols_added": [] },
  "findings": [
    {
      "kind": "scope.env",
      "detail": "New environment variable STRIPE_SECRET not in authorized scope",
      "file": ".env.example",
      "severity": "high",
      "evidence": "STRIPE_SECRET"
    }
  ],
  "scope_creep_score": "HIGH",
  "blast_radius": {
    "warnings": [
      {
        "pattern": "route-no-test",
        "message": "New API route added but no test file updated",
        "files": ["src/app/api/checkout/route.ts"],
        "suggestion": "Add tests for the new endpoint"
      }
    ]
  }
}

Tipos de descobertas

Tipo	Severidade	O que o acionou
scope.env	ALTA	Variável de ambiente não mencionada no prompt
scope.endpoint	ALTA	Rota de API adicionada sem autorização
scope.cron	ALTA	Job agendado adicionado
scope.listener	ALTA	Listener em tempo de execução (servidor, WebSocket, process.on)
scope.dep	MÉDIA	Dependência de pacote adicionada
scope.file	MÉDIA	Arquivo alterado fora do escopo do prompt
scope.feature	BAIXA	Novo símbolo que não corresponde a nenhum recurso autorizado

Telemetria

Overreach envia pings anônimos de uso: apenas contagens e enums (score, contagem de findings, SO, versão) — nunca código, prompts, caminhos de arquivo ou conteúdo de diff. Um aviso único é exibido na sua primeira revisão. Desative a qualquer momento:

export OVERREACH_TELEMETRY=0   # or DO_NOT_TRACK=1

Testes

npm test    # 241 deterministic assertions, zero API calls

Licença

MIT — gratuito e de código aberto.

Links

• npm
• GitHub
• Issues e Feedback