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

agentsmith

Auto-generate AGENTS.md from your codebase

Stop writing AGENTS.md by hand. Run agentsmith and it scans your codebase to generate a comprehensive context file that AI coding tools read automatically.

What is AGENTS.md?

AGENTS.md is an open standard for giving AI coding assistants context about your project. It's adopted by 60,000+ projects and supported by:

• Cursor
• GitHub Copilot
• Claude Code
• VS Code
• Gemini CLI
• And 20+ more tools

AI tools automatically discover and read AGENTS.md files - no configuration needed.

What agentsmith does

Instead of writing AGENTS.md manually, agentsmith scans your codebase and generates it:

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

Install

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

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

Usage

# 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 & Bug Reports

agentsmith feedback

Any feedback is helpful — bugs, ideas, questions, or just telling us what you're building.

Run agentsmith feedback and pick what you want to do: report a bug, request a feature, ask a question, share an idea, or show what you built. Bug reports auto-collect diagnostics and pre-fill the issue for you.

Privacy: agentsmith does not collect, send, or store any data. Everything runs locally on your machine. The feedback command gathers some basic info (tool versions, OS, aggregate file counts) to help with bug reports — but nothing is sent anywhere automatically. You see exactly what's collected and you choose whether to include it. Don't feel like sharing logs? A simple description is just as valuable.

You can also reach us directly:

• Report a bug
• Request a feature
• Ask a question
• Share an idea
• Show and tell

Output Modes

# 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

What's New in v1.1

🎯 API Schema Extraction

Now detects Zod validation schemas and TypeScript types from your API routes:

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

AI agents can now see your API contracts instead of guessing field names!

🧠 Cognitive Complexity Analysis

Analyzes your codebase complexity and recommends AI model effort levels:

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

🚀 Performance Improvements

• Global schema caching: O(n²) → O(n) for shared schemas
• 20-40% faster on large codebases

🌐 GraphQL Support

Extracts GraphQL schema definitions from .graphql and .gql files.

🤖 Provider-Agnostic AI Recommendations

Works with any AI provider (Claude, GPT, Gemini) - no hardcoded model names.

New in 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

All Options

Flag	Description
-o, --output <file>	Output file path (default: AGENTS.md)
--dry-run	Preview without writing file
--force	Overwrite existing AGENTS.md
--compact	Fewer details, ~20% smaller
--compress	Signatures only, ~40% smaller
--minimal	Ultra-compact, ~3K tokens
--xml	XML format output
--tree	Include file tree
--json	Also generate AGENTS.index.json
--copy	Copy output to clipboard
--include-diffs	Include uncommitted git changes
--include-git-log	Include recent commits
--split-output <size>	Split into chunks (e.g., 100kb)
--security	Include npm audit results
--monorepo	Generate for each workspace package
--mcp	Start as MCP server
--remote <url>	Analyze a GitHub repository
--watch	Auto-regenerate on file changes
--check-secrets	Scan for secrets before output

Subcommands:

Command	Description
agentsmith feedback	Open pre-filled GitHub issue with auto-collected diagnostics

MCP Server Mode

agentsmith can run as an MCP (Model Context Protocol) server for AI tool integration:

agentsmith --mcp

16 tools for AI assistants:

Category	Tools
Core	pack_codebase, read_agents
Components	search_components, get_component_info
API	get_api_routes, get_route_details, search_routes
Database	get_database_models, get_model_details
GraphQL	get_graphql_schemas
Complexity	get_complexity_report, get_complex_files
Hooks	get_hooks, get_hook_details
Search	search_codebase, get_file_info

5 MCP Resources (live subscriptions with caching):

• agents://agents-md - Auto-generated AGENTS.md
• agents://api-schemas - All API route schemas
• agents://database-schema - Database models with fields and relations
• agents://graphql-schemas - GraphQL type definitions
• agents://complexity-report - Codebase complexity analysis

Configuration

Create agentsmith.config.json in your project root:

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

What it scans

Scanner	What it finds
Components	React components with exports, props, JSDoc, complexity metrics
Variants	CVA variant options (Button: default, destructive, etc.)
Dependencies	Component imports (radix, design system, utilities)
Barrels	Index.ts re-exports for suggested import paths
Tokens	CSS variables and Tailwind config
Hooks	Custom hooks with client-only detection
API Routes	Next.js routes with methods and auth status
API Schemas	Zod validation schemas and TypeScript types for request/response
GraphQL	GraphQL schema definitions from .graphql/.gql files
Database	Prisma and Drizzle models with fields and relations
Environment	Required/optional env vars from .env.example
Patterns	react-hook-form, Zod, Zustand, tRPC, testing libs
Utilities	cn(), mode/design-system detection
Framework	Next.js, Remix, Vite with version and router type
Complexity	Cognitive complexity analysis for AI model recommendations
Statistics	Total files, lines, size, largest files
Existing docs	CLAUDE.md, .ai/ folder, .cursorrules
File Tree	Project structure visualization
Import Graph	Hub files, circular deps, unused components
TypeScript	Props interfaces, API types, model types
Tests	Test framework detection, coverage mapping
Security	npm audit vulnerabilities, outdated packages

Output

The generated AGENTS.md includes:

• TL;DR - Stack, component count, key imports, high-impact files
• Getting Started - Auto-generated setup instructions
• Project Overview - Framework, language, styling, statistics
• Critical Rules - With WRONG/RIGHT code examples
• Components - Full inventory grouped by category
• Hub Files - Most imported files (changes have wide impact)
• Unused Components - Potentially dead code warnings
• Preferred Imports - Barrel imports for cleaner code
• Custom Hooks - With client-only markers
• API Routes - Grouped by path with methods, auth, and request/response schemas
• GraphQL Schemas - Type definitions from .graphql/.gql files
• Database Models - Fields and relations
• Environment Variables - Required vs optional
• Code Patterns - Detected patterns with examples
• Design Tokens - Color tokens with usage guidance
• AI Recommendations - Model effort levels based on codebase complexity
• Commands - npm scripts
• Security - Vulnerabilities and outdated packages (with --security)

Example output

# 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

Critical Rules

1. USE EXISTING COMPONENTS

// 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"

## Why?

AI coding tools work better when they understand your codebase:

- ❌ AI generates `bg-blue-500` instead of your `bg-primary` token
- ❌ AI creates a new Button when you already have one with 9 variants
- ❌ AI ignores your patterns and conventions

With AGENTS.md:

- ✅ AI knows your components and uses them
- ✅ AI follows your design tokens
- ✅ AI matches your patterns

## Comparison

| Tool | Focus | Approach |
|------|-------|----------|
| **agentsmith** | AGENTS.md generation | Scans codebase, generates context |
| Repomix | Code packing | Packs files into single XML |
| Code2Prompt | Prompt building | Builds prompts from code |

agentsmith is specifically designed for the AGENTS.md standard with opinionated rules about component reuse and design tokens.

## Works great in

- Next.js + Tailwind + shadcn/ui projects
- React apps with component libraries
- Any TypeScript codebase with reusable components

## License

MIT

---

A [theft.studio](https://theft.studio) project