agent smith

Gere automaticamente o AGENTS.md a partir do seu código-fonte

Documentação

┏━┓┏━╸┏━╸┏┓╻╺┳╸   ┏━┓┏┳┓╻╺┳╸╻ ╻
┣━┫┃╺┓┣╸ ┃┗┫ ┃    ┗━┓┃┃┃┃ ┃ ┣━┫
╹ ╹┗━┛┗━╸╹ ╹ ╹    ┗━┛╹ ╹╹ ╹ ╹ ╹

agentsmith

Gere AGENTS.md automaticamente a partir do seu código

Pare de escrever AGENTS.md manualmente. Execute o agentsmith e ele analisa seu código para gerar um arquivo de contexto abrangente que as ferramentas de codificação com IA leem automaticamente.

O que é AGENTS.md?

AGENTS.md é um padrão aberto para dar contexto sobre seu projeto aos assistentes de codificação com IA. É adotado por mais de 60.000 projetos e suportado por:

Cursor
GitHub Copilot
Claude Code
VS Code
Gemini CLI
E mais de 20 outras ferramentas

As ferramentas de IA descobrem e leem automaticamente os arquivos AGENTS.md — sem necessidade de configuração.

O que o agentsmith faz

Em vez de escrever AGENTS.md manualmente, o agentsmith analisa seu código e o gera:

npx @jpoindexter/agent-smith

  agentsmith

  Scanning /Users/you/my-project...

  ✓ Found 279 components
  ✓ Found 5 components with CVA variants
  ✓ Found 37 color tokens
  ✓ Found 14 custom hooks
  ✓ Found 46 API routes (8 with schemas)
  ✓ Found 87 environment variables
  ✓ Detected Next.js (App Router)
  ✓ Detected shadcn/ui (26 Radix packages)
  ✓ Found cn() utility
  ✓ Found mode/design-system
  ✓ Detected 6 code patterns
  ✓ Found existing CLAUDE.md
  ✓ Found .ai/ folder (12 files)
  ✓ Found prisma schema (28 models)
  ✓ Scanned 1572 files (11.0 MB, 365,599 lines)
  ✓ Found 17 barrel exports
  ✓ Found 15 hub files (most imported)
  ✓ Found 20 Props types
  ✓ Found 40 test files (12% component coverage)

  ✓ Generated AGENTS.md
    ~11K tokens (9% of 128K context)
    Help improve agentsmith → github.com/jpoindexter/agentsmith/issues

Instalação

# Run directly (no install needed)
npx @jpoindexter/agent-smith

# Or install globally
npm install -g @jpoindexter/agent-smith

Uso

# Generate AGENTS.md in current directory
agentsmith

# Generate for a specific directory
agentsmith ./my-project

# Preview without writing (dry run)
agentsmith --dry-run

# Custom output file
agentsmith --output CONTEXT.md

# Force overwrite existing file
agentsmith --force

Feedback e Relatórios de Bugs

agentsmith feedback

Qualquer feedback é útil — bugs, ideias, perguntas ou apenas nos contar o que você está construindo.

Execute agentsmith feedback e escolha o que deseja fazer: relatar um bug, solicitar um recurso, fazer uma pergunta, compartilhar uma ideia ou mostrar o que você construiu. Relatórios de bugs coletam diagnósticos automaticamente e pré-preenchem o issue para você.

Privacidade: o agentsmith não coleta, envia ou armazena nenhum dado. Tudo é executado localmente na sua máquina. O comando de feedback coleta algumas informações básicas (versões de ferramentas, sistema operacional, contagens agregadas de arquivos) para ajudar com relatórios de bugs — mas nada é enviado automaticamente para lugar nenhum. Você vê exatamente o que é coletado e escolhe se deseja incluir. Não quer compartilhar logs? Uma descrição simples é igualmente valiosa.

Você também pode falar conosco diretamente:

Modos de Saída

# Default - comprehensive output (~11K tokens)
agentsmith

# Compact - fewer details (~20% smaller)
agentsmith --compact

# Compress - signatures only (~40% smaller)
agentsmith --compress

# Minimal - ultra-compact (~3K tokens)
agentsmith --minimal

# XML format (industry standard, matches Repomix)
agentsmith --xml

# Include file tree visualization
agentsmith --tree

Novidades na v1.1

🎯 Extração de Esquemas de API

Agora detecta esquemas de validação Zod e tipos TypeScript das suas rotas de API:

- `POST` `/api/contact`
  - **Request**: contactSchema {
      name: string (max: 100, min: 1, "Name is required")
      email: string (email: Invalid email address)
      subject: "sales" | "support" | "billing" | ...
    }

Os agentes de IA agora podem ver seus contratos de API em vez de adivinhar nomes de campos!

🧠 Análise de Complexidade Cognitiva

Analisa a complexidade do seu código e recomenda níveis de esforço de modelos de IA:

**Complexity by Area:**
- 🔴 Database: Maximum effort (most capable model)
- 🟡 API Routes: Standard effort (balanced model)
- 🟢 Utilities: Minimal effort (fast, low-cost model)

🚀 Melhorias de Desempenho

Cache global de esquemas: O(n²) → O(n) para esquemas compartilhados
20-40% mais rápido em grandes bases de código

🌐 Suporte a GraphQL

Extrai definições de esquema GraphQL de arquivos .graphql e .gql.

🤖 Recomendações de IA Independentes de Provedor

Funciona com qualquer provedor de IA (Claude, GPT, Gemini) — sem nomes de modelos codificados.

Novidades na v1.0.0

# Copy output to clipboard
agentsmith --copy

# Include uncommitted git changes
agentsmith --include-diffs

# Split large repos into chunks
agentsmith --split-output 100kb   # Creates AGENTS-001.md, AGENTS-002.md, etc.

# Include security audit (npm audit)
agentsmith --security

# Monorepo support - generate for each package
agentsmith --monorepo

# Start as MCP server for AI tool integration
agentsmith --mcp

Todas as Opções

Flag	Descrição
`-o, --output <file>`	Caminho do arquivo de saída (padrão: AGENTS.md)
`--dry-run`	Visualizar sem gravar o arquivo
`--force`	Sobrescrever AGENTS.md existente
`--compact`	Menos detalhes, ~20% menor
`--compress`	Apenas assinaturas, ~40% menor
`--minimal`	Ultra compacto, ~3K tokens
`--xml`	Saída em formato XML
`--tree`	Incluir árvore de arquivos
`--json`	Também gerar AGENTS.index.json
`--copy`	Copiar saída para a área de transferência
`--include-diffs`	Incluir alterações git não commitadas
`--include-git-log`	Incluir commits recentes
`--split-output <size>`	Dividir em partes (ex.: 100kb)
`--security`	Incluir resultados de npm audit
`--monorepo`	Gerar para cada pacote do workspace
`--mcp`	Iniciar como servidor MCP
`--remote <url>`	Analisar um repositório GitHub
`--watch`	Regenerar automaticamente em alterações de arquivos
`--check-secrets`	Verificar segredos antes da saída

Subcomandos:

Comando	Descrição
`agentsmith feedback`	Abrir issue GitHub pré-preenchido com diagnósticos coletados automaticamente

Modo Servidor MCP

O agentsmith pode ser executado como um servidor MCP (Model Context Protocol) para integração com ferramentas de IA:

agentsmith --mcp

16 ferramentas para assistentes de IA:

Categoria	Ferramentas
Núcleo	`pack_codebase`, `read_agents`
Componentes	`search_components`, `get_component_info`
API	`get_api_routes`, `get_route_details`, `search_routes`
Banco de dados	`get_database_models`, `get_model_details`
GraphQL	`get_graphql_schemas`
Complexidade	`get_complexity_report`, `get_complex_files`
Hooks	`get_hooks`, `get_hook_details`
Busca	`search_codebase`, `get_file_info`

5 Recursos MCP (assinaturas ao vivo com cache):

agents://agents-md - AGENTS.md gerado automaticamente
agents://api-schemas - Todos os esquemas de rotas de API
agents://database-schema - Modelos de banco de dados com campos e relações
agents://graphql-schemas - Definições de tipos GraphQL
agents://complexity-report - Análise de complexidade do código

Configuração

Crie agentsmith.config.json na raiz do seu projeto:

{
  "output": "AGENTS.md",
  "exclude": [
    "**/test/**",
    "**/stories/**",
    "**/fixtures/**"
  ]
}

O que ele analisa

Scanner	O que ele encontra
Componentes	Componentes React com exports, props, JSDoc, métricas de complexidade
Variantes	Opções de variantes CVA (Button: default, destructive, etc.)
Dependências	Imports de componentes (radix, design system, utilitários)
Barrels	Re-exports de Index.ts para caminhos de import sugeridos
Tokens	Variáveis CSS e configuração Tailwind
Hooks	Hooks personalizados com detecção de client-only
Rotas de API	Rotas Next.js com métodos e status de autenticação
Esquemas de API	Esquemas de validação Zod e tipos TypeScript para request/response
GraphQL	Definições de esquema GraphQL de arquivos .graphql/.gql
Banco de dados	Modelos Prisma e Drizzle com campos e relações
Ambiente	Variáveis de ambiente obrigatórias/opcionais de .env.example
Padrões	react-hook-form, Zod, Zustand, tRPC, bibliotecas de teste
Utilitários	cn(), detecção de mode/design-system
Framework	Next.js, Remix, Vite com versão e tipo de roteador
Complexidade	Análise de complexidade cognitiva para recomendações de modelos de IA
Estatísticas	Total de arquivos, linhas, tamanho, maiores arquivos
Documentação existente	CLAUDE.md, pasta .ai/, .cursorrules
Árvore de arquivos	Visualização da estrutura do projeto
Grafo de imports	Arquivos hub, dependências circulares, componentes não utilizados
TypeScript	Interfaces de props, tipos de API, tipos de modelos
Testes	Detecção de framework de teste, mapeamento de cobertura
Segurança	Vulnerabilidades de npm audit, pacotes desatualizados

Saída

O AGENTS.md gerado inclui:

TL;DR - Stack, contagem de componentes, imports principais, arquivos de alto impacto
Começando - Instruções de configuração geradas automaticamente
Visão Geral do Projeto - Framework, linguagem, estilização, estatísticas
Regras Críticas - Com exemplos de código ERRADO/CERTO
Componentes - Inventário completo agrupado por categoria
Arquivos Hub - Arquivos mais importados (alterações têm amplo impacto)
Componentes Não Utilizados - Avisos de código potencialmente morto
Imports Preferidos - Imports barrel para código mais limpo
Hooks Personalizados - Com marcadores client-only
Rotas de API - Agrupadas por caminho com métodos, autenticação e esquemas de request/response
Esquemas GraphQL - Definições de tipos de arquivos .graphql/.gql
Modelos de Banco de Dados - Campos e relações
Variáveis de Ambiente - Obrigatórias vs opcionais
Padrões de Código - Padrões detectados com exemplos
Design Tokens - Tokens de cor com orientação de uso
Recomendações de IA - Níveis de esforço de modelo com base na complexidade do código
Comandos - Scripts npm
Segurança - Vulnerabilidades e pacotes desatualizados (com --security)

Exemplo de saída

# AGENTS.md

> Auto-generated by agentsmith

## TL;DR

- **Stack**: Next.js 16.0.10 + TypeScript 5 + Tailwind 4.0.9 + shadcn/ui
- **Components**: 279 total — USE EXISTING, don't create new
- **Key imports**: `cn()` from `@/lib/utils`, `mode` from `@/design-system`
- **High-impact files**: design-system/index, utils, button, card
- **Database**: prisma with 28 models
- **API**: 46 routes (31 protected)

## Getting Started

```bash
npm install

# Set up environment
cp .env.example .env.local

# Database setup
npm run db:push
npm run db:seed

# Start development
npm run dev

Regras Críticas

1. USE COMPONENTES EXISTENTES

// WRONG
<div className="rounded border p-4">...</div>

// RIGHT
<Card><CardContent>...</CardContent></Card>

2. USE DESIGN TOKENS

// WRONG
className="bg-blue-500 text-white"

// RIGHT
className="bg-primary text-primary-foreground"


## Por quê?

As ferramentas de codificação com IA funcionam melhor quando entendem seu código:

- ❌ A IA gera `bg-blue-500` em vez do seu token `bg-primary`
- ❌ A IA cria um novo Button quando você já tem um com 9 variantes
- ❌ A IA ignora seus padrões e convenções

Com AGENTS.md:

- ✅ A IA conhece seus componentes e os utiliza
- ✅ A IA segue seus design tokens
- ✅ A IA corresponde aos seus padrões

## Comparação

| Ferramenta | Foco | Abordagem |
|------|-------|----------|
| **agentsmith** | Geração de AGENTS.md | Analisa o código, gera contexto |
| Repomix | Empacotamento de código | Empacota arquivos em um único XML |
| Code2Prompt | Construção de prompts | Constrói prompts a partir do código |

O agentsmith é especificamente projetado para o padrão AGENTS.md com regras opinativas sobre reutilização de componentes e design tokens.

## Funciona muito bem em

- Projetos Next.js + Tailwind + shadcn/ui
- Aplicativos React com bibliotecas de componentes
- Qualquer base de código TypeScript com componentes reutilizáveis

## Licença

MIT

---

Um projeto da [theft.studio](https://theft.studio)