Auto-generate AGENTS.md from your codebase
npm install @jpoindexter/agent-smith```
┏━┓┏━╸┏━╸┏┓╻╺┳╸ ┏━┓┏┳┓╻╺┳╸╻ ╻
┣━┫┃╺┓┣╸ ┃┗┫ ┃ ┗━┓┃┃┃┃ ┃ ┣━┫
╹ ╹┗━┛┗━╸╹ ╹ ╹ ┗━┛╹ ╹╹ ╹ ╹ ╹
> 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.
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.
Instead of writing AGENTS.md manually, agentsmith scans your codebase and generates it:
`bash
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
`
`bashRun directly (no install needed)
npx @jpoindexter/agent-smith
Usage
`bash
Generate AGENTS.md in current directory
agentsmithGenerate for a specific directory
agentsmith ./my-projectPreview without writing (dry run)
agentsmith --dry-runCustom output file
agentsmith --output CONTEXT.mdForce overwrite existing file
agentsmith --force
`Feedback & Bug Reports
`bash
Auto-collect diagnostics and open a pre-filled GitHub issue
agentsmith feedback
`Collects environment info (OS, Node, npm, git), project shape (framework, file stats), and your last scan results — then opens a GitHub issue with everything pre-filled. No private data (no file paths, branch names, or code) is included.
Output Modes
`bash
Default - comprehensive output (~11K tokens)
agentsmithCompact - fewer details (~20% smaller)
agentsmith --compactCompress - signatures only (~40% smaller)
agentsmith --compressMinimal - ultra-compact (~3K tokens)
agentsmith --minimalXML format (industry standard, matches Repomix)
agentsmith --xmlInclude file tree visualization
agentsmith --tree
`What's New in v1.1
$3
Now detects Zod validation schemas and TypeScript types from your API routes:`markdown
- 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!
$3
Analyzes your codebase complexity and recommends AI model effort levels:`markdown
Complexity by Area:
- 🔴 Database: Maximum effort (most capable model)
- 🟡 API Routes: Standard effort (balanced model)
- 🟢 Utilities: Minimal effort (fast, low-cost model)
`$3
- Global schema caching: O(n²) → O(n) for shared schemas
- 20-40% faster on large codebases$3
Extracts GraphQL schema definitions from .graphql and .gql files.$3
Works with any AI provider (Claude, GPT, Gemini) - no hardcoded model names.New in v1.0.0
`bash
Copy output to clipboard
agentsmith --copyInclude uncommitted git changes
agentsmith --include-diffsSplit large repos into chunks
agentsmith --split-output 100kb # Creates AGENTS-001.md, AGENTS-002.md, etc.Include security audit (npm audit)
agentsmith --securityMonorepo support - generate for each package
agentsmith --monorepoStart as MCP server for AI tool integration
agentsmith --mcp
`All Options
| Flag | Description |
|------|-------------|
|
-o, --output | 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 | Split into chunks (e.g., 100kb) |
| --security | Include npm audit results |
| --monorepo | Generate for each workspace package |
| --mcp | Start as MCP server |
| --remote | 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:
`bash
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 analysisConfiguration
Create
agentsmith.config.json in your project root:`json
{
"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
`markdown
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 installSet up environment
cp .env.example .env.localDatabase setup
npm run db:push
npm run db:seedStart development
npm run dev
`Critical Rules
$3
`tsx
// WRONG
...// RIGHT
...
`$3
`tsx
// 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` tokenWith AGENTS.md:
- ✅ AI knows your components and uses them
- ✅ AI follows your design tokens
- ✅ AI matches your patterns
| 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.
- Next.js + Tailwind + shadcn/ui projects
- React apps with component libraries
- Any TypeScript codebase with reusable components
MIT
---
A theft.studio project