@dgalvarestec/alex

🛡️ A.L.E.X. Agentic Reviewer

Agentic Logic Evaluation X-ray The multi-agent council for deep code analysis and automated review.

Status: ✅ Production Ready | Engine: Multi-Agent Reasoning (Google ADK) | Model: gemini-2.5-pro

A.L.E.X. Agentic Reviewer é um framework de análise diagnóstica profunda que realiza a "radiografia" técnica e lógica de sistemas complexos. Diferente de linters tradicionais, o A.L.E.X opera como um Micro-serviço de Inteligência, aplicando heurísticas de avaliação em múltiplas camadas para identificar falhas estruturais, vulnerabilidades de segurança e oportunidades de otimização arquitetural.

O próprio código do A.L.E.X é validado continuamente por seus agentes (alex review) — cada melhoria de segurança e qualidade neste repositório foi identificada e corrigida pelo Conselho de Agentes que ele hospeda.

🏛️ Arquitetura Multi-Agente (The Council of Agents)

O A.L.E.X opera sob o padrão de Delegação Paralela, orquestrando um conselho de agentes especialistas coordenados via Google ADK. O usuário configura apenas o catálogo de agentes de análise; revisores são derivados automaticamente quando suas dependências estão presentes.

                    ┌─────────────────────┐
                    │  ReviewOrchestrator │  ← Ponto de entrada (CLI / API)
                    └──────────┬──────────┘
                               │
                               ▼
          ┌──────────────────────────────────────────────┐
          │ ParallelAgent: agentes de análise ativos     │
          │ security, quality, sre, business, tests, ... │
          └──────────────────────┬───────────────────────┘
                                 │
                                 ▼
          ┌──────────────────────────────────────────────┐
          │ ParallelAgent: revisores derivados           │
          │ security-reviewer, performance-reviewer      │
          └──────────────────────┬───────────────────────┘
                                 │
                                 ▼
          ┌──────────────────────────────────────────────┐
          │ architect-consolidator                       │
          │ FinalReport: PASS / WARN / FAIL              │
          └──────────────────────────────────────────────┘

👑 The Architect (Orquestrador)

• Extrai metadados do diff/sourceCode via parser linear O(n)
• Delega em paralelo para os agentes habilitados no perfil
• Executa revisores apenas quando suas dependências de agentes estão presentes
• Consolida feedbacks conflitantes em um veredito final único
• Aplica retry exponencial com jitter para falhas transitórias do provedor

Agentes de Análise

Agente	Padrão	Foco
security-auditor	Sim	OWASP Top 10, path traversal, ReDoS, timing attacks, vazamento de credenciais e data leakage
clean-coder	Sim	S.O.L.I.D, DRY, complexidade ciclomática, No-Any Policy e Contract-First Development
sre-agent	Sim	Memory leaks, OOM, event loop blocking, timeouts, retry, rate limiting e eficiência operacional
business-proxy	Sim	Regras de domínio via RAG dinâmico, READMEs e documentação de arquitetura local
error-handling-specialist	Não	Caminhos de erro, fallback seguro, resiliência e falhas recuperáveis
test-strategist	Não	Qualidade de testes, cobertura de regressão, contratos e comportamento de CI
observability-engineer	Não	Logs, métricas, traces, debuggability e diagnóstico sem vazamento de segredo
docs-maintainer	Não	Documentação de produto, API, operação e superfície de comandos/configuração
scalability-architect	Não	Escalabilidade, concorrência, batching, limites de memória e crescimento de dados

Revisores Derivados

Revisor	Dependências	Foco
security-reviewer	sre-agent, clean-coder	Revisa achados de confiabilidade e qualidade sob a ótica de segurança
performance-reviewer	security-auditor, clean-coder	Revisa achados de segurança e qualidade sob a ótica de performance

Use alex review all ou alex review --agents all para executar todos os agentes de análise. Revisores não são habilitados diretamente pelo usuário.

🛠️ Stack Tecnológica

Componente	Tecnologia	Detalhes
Language	TypeScript	Tipagem estrita; No-Any Policy enforced
Framework	Google ADK	@google/adk + @google/adk-devtools
API	Express 5	Rate limiting, Auth Bearer, Zod validation
CLI	Commander.js	alex review e alex analyze <file>
Reasoning	Gemini 2.5 Pro	Configurável via ALEX_MODEL no .env
Contracts	Zod	Schemas runtime para entrada e saída dos agentes

📋 Pré-requisitos

• Node.js: ^24.13.0 ou superior
• NPM: ^11.8.0 ou superior
• Git: Instalado e em PATH (necessário para alex review)

[!WARNING] Rate Limits: Devido à natureza paralela do Council of Agents, use gemini-2.5-pro como mínimo. O gemini-2.0-flash frequentemente apresenta HTTP 429 por exaustão de cota de requisições simultâneas.

🚀 Quick Start

Usar como CLI publicada

npm install -g @dgalvarestec/alex

Para instalar direto deste repositório antes da publicação no npm:

npm install -g github:dgalvares/A.L.E.X.-Agentic-Reviewer

Antes do primeiro review, configure a chave do Gemini. Sem isso, comandos como alex review e alex analyze falham ao inicializar a análise.

Faça o setup uma única vez:

alex config set-key
alex config set-model gemini-2.5-pro
alex config show

O CLI salva essa configuração em ~/.alex/config.json. Variáveis de ambiente continuam tendo prioridade, então CI/CD pode usar GEMINI_API_KEY e ALEX_MODEL normalmente. O comando alex config set-key solicita a chave em modo oculto, sem gravá-la no histórico do shell.

Depois disso, execute o review:

alex review

Desenvolvimento local

1. Instalação de Dependências

npm install

2. Configuração de Ambiente

Crie um arquivo .env na raiz (use .env.example como base):

# Obrigatório
GEMINI_API_KEY="sua_chave_aqui"

# Opcional — padrão: gemini-2.5-pro
ALEX_MODEL="gemini-2.5-pro"

# Obrigatório para a API REST (bloqueia acesso se ausente)
API_BEARER_TOKEN="sua_senha_secreta"

# Para deploy em Cloud Run/Kubernetes (CIDR da rede interna)
# TRUSTED_PROXY_CIDR="10.0.0.0/8"

3. Compilar

npm run build

4. Validar

npm run typecheck
npm test

💻 Modos de Uso

CLI — opções globais

Opção	Descrição
-h, --help	Mostra ajuda do comando atual. Ex: alex ci --help.
-V, --version	Mostra a versão instalada do CLI, derivada do package.json.

CLI — alex review

Analisa as modificações locais via git diff HEAD e inclui arquivos novos ainda untracked no relatório local. Ideal para uso antes do commit.

# Com o modelo padrão (definido em .env)
alex review

# Com modelo específico
alex review -m gemini-2.5-pro

# Permite achados tambem em trechos fora do diff, usando o contexto completo dos arquivos alterados
alex review --include-context-findings

# Inclui a codebase rastreada pelo Git como contexto, mantendo achados restritos ao diff
alex review --include-codebase-context

# Remove limites de tamanho/quantidade do contexto de codebase. Use por conta e risco.
alex review --include-codebase-context --unsafe-disable-codebase-limits

Por padrao, alex review usa arquivos completos apenas como contexto e o consolidator deve reportar somente problemas causados por linhas tocadas pelo diff.

Parâmetros e opções:

Opção	Descrição
[profile]	Perfil opcional de agentes. Aceita default, all ou lista separada por vírgula/espaço. Ex: alex review all.
-m, --model <modelo>	Modelo LLM da análise. Se omitido, usa ALEX_MODEL, configuração persistente ou fallback.
--preset <preset>	Preset semantico de review. Aceita fast, security, quality, ops, docs e release.
--agents <lista>	Agentes habilitados. Ex: default,test-strategist. Tem precedência sobre [profile].
--disable-agents <lista>	Remove agentes do conjunto resolvido. Ex: sre-agent.
--agent-models <mapa>	Override de modelo por agente. Ex: security-auditor:gemini-2.0-flash,architect-consolidator:gemini-2.5-pro.
--include-context-findings	Permite achados fora das linhas alteradas usando o contexto completo dos arquivos modificados.
--include-codebase-context	Inclui a codebase rastreada pelo Git como contexto para validar o diff. Tambem aceita ALEX_INCLUDE_CODEBASE_CONTEXT=true. Default: desligado.
--unsafe-disable-codebase-limits	Remove limites de tamanho/quantidade do contexto de codebase. Tambem aceita ALEX_UNSAFE_DISABLE_CODEBASE_LIMITS=true. Mantem filtros de seguranca.

Output exemplo:

🛡️ A.L.E.X Code Review Iniciado

[ALEX] Análise finalizada com sucesso.

Veredito Final: FAIL
--------------------------------------------------
Foram identificados 2 Blockers críticos de segurança...
--------------------------------------------------

[Blocker] security-auditor
Arquivo: src/server.ts (Linha 25)
Mensagem: Auth Fail-Open — API acessível sem token configurado.

CLI — alex analyze <arquivo>

Analisa um arquivo completo estruturalmente. Ideal para validar um módulo específico.

alex analyze src/services/payment.service.ts

Parâmetros e opções:

Opção	Descrição
<arquivo>	Caminho do arquivo a analisar. Deve existir dentro do workspace, ser arquivo regular e ter até 1MB.
-m, --model <modelo>	Modelo LLM da análise. Se omitido, usa ALEX_MODEL, configuração persistente ou fallback.
--preset <preset>	Preset semantico de review. Ex: quality, docs, release.
--agents <lista>	Agentes habilitados. Ex: default,error-handling-specialist.
--disable-agents <lista>	Remove agentes do conjunto resolvido. Ex: business-proxy.
--agent-models <mapa>	Override de modelo por agente. Ex: clean-coder:gemini-2.0-flash.

Perfis Dinâmicos de Agentes

Por padrão, default mantém o conselho atual. Agentes adicionais podem ser habilitados por comando, variável de ambiente ou configuração persistente:

alex review --agents default,test-strategist,error-handling-specialist
alex review --preset security
alex review release
alex review --agents all
alex review all
alex ci --diff-file pr.diff --agents default,docs-maintainer --disable-agents sre-agent
alex config set-agents default,observability-engineer
alex config set-agents all
alex config disable-agent docs-maintainer

Use all para rodar todos os agentes de análise registrados. Agentes opt-in disponíveis: error-handling-specialist, test-strategist, observability-engineer, docs-maintainer e scalability-architect. Agentes revisores não são configuráveis pelo usuário: eles entram automaticamente quando suas dependências existem. security-reviewer roda quando sre-agent e clean-coder estão ativos; performance-reviewer roda quando security-auditor e clean-coder estão ativos.

Review Presets

Presets são atalhos semanticos para perfis de agentes. --agents continua tendo precedência quando você quiser controlar a lista manualmente.

Preset	Agentes
default	security-auditor, clean-coder, sre-agent, business-proxy
fast	clean-coder, security-auditor
security	security-auditor, error-handling-specialist, sre-agent, clean-coder
quality	clean-coder, test-strategist, error-handling-specialist
ops	sre-agent, observability-engineer, scalability-architect, error-handling-specialist, security-auditor
docs	docs-maintainer, business-proxy
release	all

Aliases: quick -> fast, prod -> ops, full/all -> release.

Agente de análise	Perfil	Foco
security-auditor	default	Vulnerabilidades, conformidade e vazamento de dados
clean-coder	default	Manutenibilidade, design, DRY e contratos
sre-agent	default	Performance, resiliência e eficiência operacional
business-proxy	default	Regras de negócio e documentação local via RAG
error-handling-specialist	opt-in / all	Fail-open/fail-closed, retries, rollback e idempotência
test-strategist	opt-in / all	Cobertura, regressão, casos negativos e fragilidade de testes
observability-engineer	opt-in / all	Logs, métricas, traces, correlation IDs e auditabilidade
docs-maintainer	opt-in / all	README, exemplos, changelog, docs de API e runbooks
scalability-architect	opt-in / all	Throughput, concorrência, filas, cache e multi-instância

Revisor automático	Dependências	Função
security-reviewer	sre-agent, clean-coder	Verifica se achados de performance/qualidade introduzem risco de segurança
performance-reviewer	security-auditor, clean-coder	Verifica se achados de segurança/qualidade introduzem gargalos

CLI — alex config

Gerencia a configuração persistente em ~/.alex/config.json. Variáveis de ambiente têm precedência sobre essa configuração.

Comando	Descrição
alex config set-key	Salva GEMINI_API_KEY usando entrada oculta, sem gravar a chave no histórico do shell.
alex config set-model <model>	Define o modelo padrão persistente do CLI.
alex config set-preset <preset>	Define o preset persistente. Ex: security.
alex config clear-preset	Remove o preset persistente.
alex config set-agents <agents>	Define o perfil persistente de agentes. Ex: default,observability-engineer.
alex config disable-agent <agents>	Define agentes persistentes a remover do perfil resolvido. Ex: docs-maintainer.
alex config show	Mostra a configuração ativa sem exibir segredos.

CLI — alex ci

Analisa um diff de PR em CI e gera relatório Markdown ou JSON para automações.

alex ci --diff-file pr.diff --output-file alex-review.md --pr-number <PR>

Parâmetros e opções:

Opção	Descrição
--diff-file <arquivo>	Obrigatório. Arquivo com o diff do PR. Deve existir dentro do workspace e ter até 10MB.
--output-file <arquivo>	Arquivo de saída do relatório. Padrão: alex-review.md.
--format <formato>	Formato de saída: markdown ou json. Padrão: markdown.
--project <nome>	Nome do projeto/repositório no metadata da análise. Padrão: nome do diretório atual.
--pr-number <numero>	Número do PR usado para enriquecer o título do relatório.
-m, --model <modelo>	Modelo LLM da análise. Se omitido, usa ALEX_MODEL, configuração persistente ou fallback.
--fail-on-fail	Retorna exit code 1 quando o veredito final for FAIL.
--preset <preset>	Preset semantico de review. Ex: security, ops, release.
--agents <lista>	Agentes habilitados. Ex: default,docs-maintainer.
--disable-agents <lista>	Remove agentes do conjunto resolvido. Ex: sre-agent.
--agent-models <mapa>	Override de modelo por agente. Ex: security-auditor:gemini-2.0-flash.
--include-context-findings	Permite achados fora das linhas alteradas usando o contexto completo dos arquivos modificados.
--include-codebase-context	Inclui a codebase rastreada pelo Git como contexto para validar o diff. Tambem aceita ALEX_INCLUDE_CODEBASE_CONTEXT=true. Default: desligado.
--unsafe-disable-codebase-limits	Remove limites de tamanho/quantidade do contexto de codebase. Tambem aceita ALEX_UNSAFE_DISABLE_CODEBASE_LIMITS=true. Mantem filtros de seguranca.

[!NOTE] Proteções de Segurança na CLI:

• Path Traversal Prevention via fs.realpath (anti-symlink bypass)
• Data Leakage Blocklist: .pem, .key, .pfx, .sqlite, id_rsa, .npmrc, etc.
• Limite de 1MB por arquivo (anti-OOM)
• Git diff limitado a 10MB com stream via spawn (anti-DoS)
• Contexto amplo de codebase limitado a 8MB, 500 arquivos e 512KB por arquivo, com sanitizacao de valores sensiveis por arquivo.
• --unsafe-disable-codebase-limits remove apenas os limites de tamanho/quantidade do contexto amplo; filtros de seguranca, binarios e arquivos ruidosos continuam ativos.

API REST — POST /v1/analyze

Para integração com CI/CD (GitHub Actions, GitLab CI).

npm run start:api
# API disponível em http://localhost:3000

Endpoint: POST /v1/analyze

Headers obrigatórios:

Authorization: Bearer <API_BEARER_TOKEN>
Content-Type: application/json

Payload:

{
  "streamId": "uuid-opcional",
  "metadata": {
    "stack": ".net",
    "project": "MeuProjeto",
    "preset": "quality",
    "disabledAgents": ["docs-maintainer"],
    "analysisMode": "DIFF_WITH_CONTEXT"
  },
  "diff": "conteúdo_do_git_diff_aqui"
}

Resposta:

{
  "streamId": "...",
  "verdict": "FAIL",
  "summary": "Foram encontrados 2 Blockers...",
  "issues": [
    {
      "origin": "security-auditor",
      "severity": "Blocker",
      "file": "src/api/controller.cs",
      "line": 42,
      "message": "SQL Injection via concatenação direta.",
      "codeSnippet": "var query = \"SELECT * FROM users WHERE id = \" + id;"
    }
  ],
  "timestamp": "2026-04-24T19:00:00Z"
}

Health Check:

curl http://localhost:3000/health
# {"status":"UP","version":"1.0.0"}

ADK Web UI (Debug)

Interface visual para inspecionar o fluxo de raciocínio dos agentes.

npx adk web
# http://localhost:8000

GitHub Actions — alex review

Existem dois templates:

• .github/workflows/alex-pr-review.yml: usado neste repositório, buildando o A.L.E.X localmente.
• .github/workflows/alex-pr-review.consumer.yml: copie para outros repositórios; ele instala @dgalvarestec/alex como CLI global.

O workflow consumidor permite acionar o A.L.E.X em PRs:

• manualmente via workflow_dispatch informando pr_number;
• por comentário contendo alex review no PR ou em review comments.
• por comentário com perfil de agentes, como alex review all, alex review --agents all ou alex review --agents default,test-strategist --disable-agents docs-maintainer.

Configure o secret GEMINI_API_KEY no repositório. Opcionalmente, configure as variáveis ALEX_MODEL, ALEX_PRESET, ALEX_AGENTS, ALEX_DISABLED_AGENTS, ALEX_INCLUDE_CODEBASE_CONTEXT e ALEX_UNSAFE_DISABLE_CODEBASE_LIMITS para trocar o modelo, o preset/perfil de agentes padrão e o volume de contexto usado no diff.

Para falhas transitórias do provedor, o A.L.E.X aplica retry exponencial com jitter preservando o ciclo interno do ADK. Os padrões são ALEX_AGENT_MAX_RETRIES=2 e ALEX_AGENT_RETRY_BASE_MS=1000. Para evitar retry storm, perfis com múltiplos agentes não reexecutam o pipeline inteiro por padrão; use ALEX_ALLOW_MULTI_AGENT_PIPELINE_RETRY=true apenas se aceitar esse custo.

Na API, ALEX_API_MAX_CONCURRENT_ANALYSES controla o backpressure global de análises simultâneas. O padrão é 2; quando o limite é atingido, a API responde 503 com Retry-After.

O workflow consumidor executa:

gh pr diff <PR> > pr.diff
alex ci --diff-file pr.diff --output-file alex-review.md --pr-number <PR>

Use --include-context-findings no alex ci quando quiser permitir que o relatorio inclua problemas encontrados fora das linhas alteradas pelo diff. Use ALEX_INCLUDE_CODEBASE_CONTEXT=true no workflow, ou alex ci --include-codebase-context, quando quiser enviar a codebase rastreada pelo Git como contexto adicional. Essa opcao fica desligada por padrao e aumenta custo/latencia. Use ALEX_UNSAFE_DISABLE_CODEBASE_LIMITS=true ou --unsafe-disable-codebase-limits apenas quando aceitar risco de custo, memoria e limite de contexto do modelo.

Comentários alex review só executam para usuários com permissão write, maintain ou admin, evitando consumo indevido da chave em repositórios públicos.

Publicação no npm

O repositório usa publicação por Trusted Publishing (OIDC) — sem NPM_TOKEN armazenado:

• .github/workflows/publish.yml: valida, empacota, publica no npm e só então cria um draft de GitHub Release com release notes geradas automaticamente para revisão.
• .github/workflows/preview-manual.yml: gera .tgz preview como artifact, sem publicar.

Configure no npm o Trusted Publisher do pacote @dgalvarestec/alex:

Provider: GitHub Actions
Repository: dgalvares/A.L.E.X.-Agentic-Reviewer
Workflow filename: publish.yml
Environment: npm-production

No GitHub, crie o environment npm-production (com aprovação manual opcional).

Publicação de versão:

npm version patch   # ou minor / major
npm run typecheck
npm test
git push origin main --follow-tags

A GitHub Release draft só é criada após o npm publish concluir com sucesso. O pacote .tgz anexado à release é o mesmo artefato publicado no npm, reduzindo divergência entre release notes, tag e conteúdo publicado. Revise as notas geradas antes de publicar a release.

📂 Estrutura do Projeto

A.L.E.X/
├── src/
│   ├── agents/
│   │   └── specialists.ts     # Security, Clean Coder, SRE, Business Proxy
│   ├── prompts/
│   │   └── index.ts           # Prompts dos agentes externalizados
│   ├── schemas/
│   │   └── contracts.ts       # Zod schemas: AnalysisPayload, FinalReport, etc.
│   ├── tools/
│   │   └── diff_tools.ts      # Parser O(n) para metadados de diff/sourceCode
│   ├── utils/
│   │   ├── parser.ts          # Helper compartilhado de extração de JSON
│   │   ├── diff_sanitizer.ts  # Sanitização de diffs: redact secrets e arquivos sensíveis
│   │   └── sensitive_paths.ts # Blocklist centralizada de paths/extensões proibidos
│   ├── agent.ts               # rootAgent (ADK entry point)
│   ├── cli.ts                 # CLI: comandos review e analyze
│   ├── config.ts              # Configuração centralizada (FALLBACK_MODEL, getDefaultModel)
│   ├── orchestrator.ts        # ReviewOrchestrator — coordenação imutável do pipeline
│   └── server.ts              # API Express com Auth, Rate Limit e Zod
├── tests/
│   └── evaluation/            # Arquivos .test.json para ADK Eval
├── .agents/
│   └── rules.md               # Regras imutáveis do workspace
├── BACKLOG.md                 # Débitos arquiteturais para iterações futuras
└── .env.example               # Template de configuração

🔒 Segurança da API

Proteção	Implementação
Autenticação	Bearer Token via SHA-256 hash + crypto.timingSafeEqual (anti Timing Attack)
Rate Limiting	10 req/min/IP com express-rate-limit (RFC headers)
Validação de Input	AnalysisPayloadSchema via Zod após auth/rate limit, antes do processamento
Fail-Closed	API retorna 500 se API_BEARER_TOKEN não estiver configurado
Trust Proxy	Restrito a loopback por padrão; configurável via TRUSTED_PROXY_CIDR
Body Limit	25MB máximo; jsonParser aplicado após auth para economizar parse desnecessário
Sanitização de Diff	diff_sanitizer.ts redacta secrets e arquivos sensíveis antes de enviar ao LLM
Limite de Confiança do LLM	Código, diffs e comentários analisados são tratados como conteúdo não confiável; instruções embutidas nesses inputs não devem substituir prompts do sistema
Imutabilidade	Orquestrador cria normalizedInput via spread — sem mutação do payload original

[!WARNING] Ambientes multi-pod (Cloud Run/Kubernetes): O MemoryStore padrão do rate limiter não é compartilhado entre instâncias. Para deploy distribuído, configure RedisStore — veja BACKLOG.md [INFRA-01].

📜 Regras do Workspace (.agents/rules.md)

• Especialização Estrita: Agentes proibidos de opinar fora de seu domínio técnico.
• Protocolo de Consenso: Um Blocker de segurança resulta em FAIL imediato.
• Rastreabilidade: Todo apontamento deve conter origin (ex: security-auditor).
• Tipagem Estrita: Severidades via Enum (Blocker, Critical, Major, Minor, Info).
• Prioridade de Domínio: Regras de negócio documentadas sobrepõem preferências estéticas.
• Filtro de Ingestão: Ignorar bin, obj, node_modules, dist.
• Obrigatoriedade de Review: Todo novo código deve ser validado via alex review antes do merge.

📌 Backlog & Próximos Passos

Os débitos arquiteturais identificados pelo próprio A.L.E.X estão documentados em BACKLOG.md, incluindo:

• [ARCH-01/02] Refatoração da CLI (God Class → Services)
• [INFRA-01] RedisStore para rate limiting distribuído
• [QUAL-03] Testes de unidade (ADK Eval)

© 2026 DgAlvaresTEC — Advanced Agentic Systems