agent smith

Genera automáticamente AGENTS.md desde tu base de código

Documentación

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

agentsmith

Genera automáticamente AGENTS.md desde tu código base

Deja de escribir AGENTS.md a mano. Ejecuta agentsmith y escaneará tu código base para generar un archivo de contexto completo que las herramientas de IA de codificación leen automáticamente.

¿Qué es AGENTS.md?

AGENTS.md es un estándar abierto para dar contexto a los asistentes de IA de codificación sobre tu proyecto. Está adoptado por más de 60,000 proyectos y es compatible con:

Cursor
GitHub Copilot
Claude Code
VS Code
Gemini CLI
Y más de 20 herramientas adicionales

Las herramientas de IA descubren y leen automáticamente los archivos AGENTS.md — sin necesidad de configuración.

Qué hace agentsmith

En lugar de escribir AGENTS.md manualmente, agentsmith escanea tu código base y lo genera:

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

Instalación

# 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

Comentarios e Informes de Errores

agentsmith feedback

Cualquier comentario es útil — errores, ideas, preguntas, o simplemente contarnos qué estás construyendo.

Ejecuta agentsmith feedback y elige lo que quieras hacer: reportar un error, solicitar una función, hacer una pregunta, compartir una idea, o mostrar lo que has construido. Los informes de errores recopilan automáticamente diagnósticos y rellenan el issue por ti.

Privacidad: agentsmith no recopila, envía ni almacena ningún dato. Todo se ejecuta localmente en tu máquina. El comando de comentarios recopila información básica (versiones de herramientas, sistema operativo, recuentos agregados de archivos) para ayudar con los informes de errores — pero no se envía nada automáticamente a ningún lugar. Ves exactamente lo que se recopila y eliges si incluirlo. ¿No quieres compartir registros? Una descripción simple es igual de valiosa.

También puedes contactarnos directamente:

Modos de Salida

# 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

Novedades en v1.1

🎯 Extracción de Esquemas de API

Ahora detecta esquemas de validación Zod y tipos de TypeScript de tus rutas 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" | ...
    }

¡Los agentes de IA ahora pueden ver tus contratos de API en lugar de adivinar los nombres de los campos!

🧠 Análisis de Complejidad Cognitiva

Analiza la complejidad de tu código base y recomienda niveles de esfuerzo para 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)

🚀 Mejoras de Rendimiento

Caché global de esquemas: O(n²) → O(n) para esquemas compartidos
20-40% más rápido en código base grande

🌐 Soporte GraphQL

Extrae definiciones de esquemas GraphQL de archivos .graphql y .gql.

🤖 Recomendaciones de IA Independientes del Proveedor

Funciona con cualquier proveedor de IA (Claude, GPT, Gemini) — sin nombres de modelos codificados.

Nuevo en 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 las Opciones

Bandera	Descripción
`-o, --output <file>`	Ruta del archivo de salida (predeterminado: AGENTS.md)
`--dry-run`	Vista previa sin escribir archivo
`--force`	Sobrescribir AGENTS.md existente
`--compact`	Menos detalles, ~20% más pequeño
`--compress`	Solo firmas, ~40% más pequeño
`--minimal`	Ultra compacto, ~3K tokens
`--xml`	Salida en formato XML
`--tree`	Incluir árbol de archivos
`--json`	También generar AGENTS.index.json
`--copy`	Copiar salida al portapapeles
`--include-diffs`	Incluir cambios git no confirmados
`--include-git-log`	Incluir commits recientes
`--split-output <size>`	Dividir en fragmentos (ej., 100kb)
`--security`	Incluir resultados de npm audit
`--monorepo`	Generar para cada paquete del workspace
`--mcp`	Iniciar como servidor MCP
`--remote <url>`	Analizar un repositorio de GitHub
`--watch`	Regenerar automáticamente al cambiar archivos
`--check-secrets`	Escanear secretos antes de la salida

Subcomandos:

Comando	Descripción
`agentsmith feedback`	Abrir issue de GitHub prellenado con diagnósticos recopilados automáticamente

Modo Servidor MCP

agentsmith puede ejecutarse como un servidor MCP (Model Context Protocol) para integración con herramientas de IA:

agentsmith --mcp

16 herramientas para asistentes de IA:

Categoría	Herramientas
Núcleo	`pack_codebase`, `read_agents`
Componentes	`search_components`, `get_component_info`
API	`get_api_routes`, `get_route_details`, `search_routes`
Base de datos	`get_database_models`, `get_model_details`
GraphQL	`get_graphql_schemas`
Complejidad	`get_complexity_report`, `get_complex_files`
Hooks	`get_hooks`, `get_hook_details`
Búsqueda	`search_codebase`, `get_file_info`

5 Recursos MCP (suscripciones en vivo con caché):

agents://agents-md - AGENTS.md generado automáticamente
agents://api-schemas - Todos los esquemas de rutas de API
agents://database-schema - Modelos de base de datos con campos y relaciones
agents://graphql-schemas - Definiciones de tipos GraphQL
agents://complexity-report - Análisis de complejidad del código base

Configuración

Crea agentsmith.config.json en la raíz de tu proyecto:

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

Qué escanea

Escáner	Qué encuentra
Componentes	Componentes React con exports, props, JSDoc, métricas de complejidad
Variantes	Opciones de variantes CVA (Button: default, destructive, etc.)
Dependencias	Imports de componentes (radix, sistema de diseño, utilidades)
Barrels	Re-exports de Index.ts para rutas de import sugeridas
Tokens	Variables CSS y configuración de Tailwind
Hooks	Hooks personalizados con detección solo-cliente
Rutas de API	Rutas Next.js con métodos y estado de autenticación
Esquemas de API	Esquemas de validación Zod y tipos de TypeScript para solicitud/respuesta
GraphQL	Definiciones de esquemas GraphQL de archivos .graphql/.gql
Base de datos	Modelos Prisma y Drizzle con campos y relaciones
Entorno	Variables de entorno requeridas/opcionales de .env.example
Patrones	react-hook-form, Zod, Zustand, tRPC, librerías de testing
Utilidades	cn(), detección de modo/sistema de diseño
Framework	Next.js, Remix, Vite con versión y tipo de router
Complejidad	Análisis de complejidad cognitiva para recomendaciones de modelos de IA
Estadísticas	Total de archivos, líneas, tamaño, archivos más grandes
Docs existentes	CLAUDE.md, carpeta .ai/, .cursorrules
Árbol de archivos	Visualización de la estructura del proyecto
Grafo de imports	Archivos centrales, dependencias circulares, componentes no utilizados
TypeScript	Interfaces de props, tipos de API, tipos de modelos
Pruebas	Detección de framework de pruebas, mapeo de cobertura
Seguridad	Vulnerabilidades de npm audit, paquetes desactualizados

Salida

El AGENTS.md generado incluye:

TL;DR - Stack, recuento de componentes, imports clave, archivos de alto impacto
Primeros pasos - Instrucciones de configuración generadas automáticamente
Resumen del proyecto - Framework, lenguaje, estilos, estadísticas
Reglas críticas - Con ejemplos de código INCORRECTO/CORRECTO
Componentes - Inventario completo agrupado por categoría
Archivos centrales - Archivos más importados (los cambios tienen amplio impacto)
Componentes no utilizados - Advertencias de código potencialmente muerto
Imports preferidos - Imports de barrel para código más limpio
Hooks personalizados - Con marcadores solo-cliente
Rutas de API - Agrupadas por ruta con métodos, autenticación y esquemas de solicitud/respuesta
Esquemas GraphQL - Definiciones de tipos de archivos .graphql/.gql
Modelos de base de datos - Campos y relaciones
Variables de entorno - Requeridas vs opcionales
Patrones de código - Patrones detectados con ejemplos
Tokens de diseño - Tokens de color con guía de uso
Recomendaciones de IA - Niveles de esfuerzo del modelo según la complejidad del código base
Comandos - Scripts npm
Seguridad - Vulnerabilidades y paquetes desactualizados (con --security)

Ejemplo de salida

# 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

Reglas Críticas

1. USA COMPONENTES EXISTENTES

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

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

2. USA TOKENS DE DISEÑO

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

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


## ¿Por qué?

Las herramientas de IA de codificación funcionan mejor cuando entienden tu código base:

- ❌ La IA genera `bg-blue-500` en lugar de tu token `bg-primary`
- ❌ La IA crea un nuevo Button cuando ya tienes uno con 9 variantes
- ❌ La IA ignora tus patrones y convenciones

Con AGENTS.md:

- ✅ La IA conoce tus componentes y los usa
- ✅ La IA sigue tus tokens de diseño
- ✅ La IA coincide con tus patrones

## Comparación

| Herramienta | Enfoque | Método |
|------|-------|----------|
| **agentsmith** | Generación de AGENTS.md | Escanea código base, genera contexto |
| Repomix | Empaquetado de código | Empaqueta archivos en un solo XML |
| Code2Prompt | Construcción de prompts | Construye prompts desde el código |

agentsmith está específicamente diseñado para el estándar AGENTS.md con reglas opinadas sobre reutilización de componentes y tokens de diseño.

## Funciona muy bien en

- Proyectos Next.js + Tailwind + shadcn/ui
- Aplicaciones React con librerías de componentes
- Cualquier código base TypeScript con componentes reutilizables

## Licencia

MIT

---

Un proyecto de [theft.studio](https://theft.studio)