Agent Smith

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

agentsmith

根据代码库自动生成 AGENTS.md

别再手动编写 AGENTS.md 了。运行 agentsmith，它会扫描代码库，生成一份全面的上下文文件，供 AI 编码工具自动读取。

什么是 AGENTS.md？

AGENTS.md 是一项开放标准，用于向 AI 编码助手提供项目上下文。已有 60,000 多个项目采用，并受到以下工具支持：

• Cursor
• GitHub Copilot
• Claude Code
• VS Code
• Gemini CLI
• 以及 20 多种其他工具

AI 工具会自动发现并读取 AGENTS.md 文件，无需配置。

agentsmith 的功能

agentsmith 无需手动编写 AGENTS.md，而是扫描代码库并生成文件：

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

安装

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

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

用法

# 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

反馈与错误报告

agentsmith feedback

任何反馈都很有帮助——无论是错误、想法、问题，还是告诉我们你正在构建什么。

运行 agentsmith feedback，然后选择你想做的事：报告错误、请求功能、提问、分享想法，或展示你的作品。错误报告会自动收集诊断信息，并为你预先填写问题内容。

隐私： agentsmith 不会收集、发送或存储任何数据。所有操作都在你的设备本地运行。反馈命令会收集一些基本信息（工具版本、操作系统、文件数量汇总），以协助错误报告，但不会自动向任何地方发送信息。你可以清楚地看到收集了哪些信息，并自行决定是否附上。不想分享日志？简单描述同样很有价值。

你也可以直接联系我们：

• 报告错误
• 请求功能
• 提问
• 分享想法
• 展示与分享

输出模式

# 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

v1.1 新功能

🎯 API Schema 提取

现在可以从 API 路由中检测 Zod 验证 schema 和 TypeScript 类型：

- `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 Agent 现在可以查看你的 API 契约，而不用猜测字段名称！

🧠 认知复杂度分析

分析代码库的复杂度，并推荐 AI 模型的工作强度等级：

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

🚀 性能改进

• 全局 schema 缓存：O(n²) → O(n)，适用于共享 schema
• 大型代码库的速度提升 20-40%

🌐 GraphQL 支持

从 .graphql 和 .gql 文件中提取 GraphQL schema 定义。

🤖 不依赖特定提供商的 AI 建议

适用于任何 AI 提供商（Claude、GPT、Gemini），不硬编码模型名称。

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

所有选项

标志	说明
-o, --output <file>	输出文件路径（默认：AGENTS.md）
--dry-run	预览但不写入文件
--force	覆盖现有的 AGENTS.md
--compact	减少细节，体积约缩小 20%
--compress	仅包含签名，体积约缩小 40%
--minimal	超精简，约 3K 个 token
--xml	以 XML 格式输出
--tree	包含文件树
--json	同时生成 AGENTS.index.json
--copy	将输出复制到剪贴板
--include-diffs	包含未提交的 git 更改
--include-git-log	包含近期提交
--split-output <size>	拆分成多个块（例如 100kb）
--security	包含 npm audit 结果
--monorepo	为每个工作区包生成文件
--mcp	以 MCP 服务形式启动
--remote <url>	分析 GitHub 仓库
--watch	文件更改时自动重新生成
--check-secrets	输出前扫描密钥

子命令：

命令	说明
agentsmith feedback	打开预先填写内容的 GitHub 问题，并自动收集诊断信息

MCP 服务模式

agentsmith 可以作为 MCP（Model Context Protocol）服务运行，以集成 AI 工具：

agentsmith --mcp

为 AI 助手提供 16 个工具：

类别	工具
核心	pack_codebase、read_agents
组件	search_components、get_component_info
API	get_api_routes、get_route_details、search_routes
数据库	get_database_models、get_model_details
GraphQL	get_graphql_schemas
复杂度	get_complexity_report、get_complex_files
Hooks	get_hooks、get_hook_details
搜索	search_codebase、get_file_info

5 个 MCP 资源（实时订阅并缓存）：

• agents://agents-md - 自动生成的 AGENTS.md
• agents://api-schemas - 所有 API 路由架构
• agents://database-schema - 包含字段和关系的数据库模型
• agents://graphql-schemas - GraphQL 类型定义
• agents://complexity-report - 代码库复杂度分析

配置

在项目根目录中创建 agentsmith.config.json：

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

扫描内容

扫描器	查找内容
组件	包含导出、props、JSDoc 和复杂度指标的 React 组件
变体	CVA 变体选项（Button：default、destructive 等）
依赖项	组件导入（radix、设计系统、工具）
Barrels	用于建议导入路径的 Index.ts 重新导出
Tokens	CSS 变量和 Tailwind 配置
Hooks	自定义 Hooks，并检测是否仅限客户端
API 路由	包含方法和身份验证状态的 Next.js 路由
API 架构	用于请求/响应的 Zod 验证架构和 TypeScript 类型
GraphQL	来自 .graphql/.gql 文件的 GraphQL 架构定义
数据库	包含字段和关系的 Prisma 和 Drizzle 模型
环境变量	来自 .env.example 的必需/可选环境变量
模式	react-hook-form、Zod、Zustand、tRPC、测试库
工具	cn()、mode/设计系统检测
框架	Next.js、Remix、Vite，以及版本和路由器类型
复杂度	用于 AI 模型建议的认知复杂度分析
统计信息	文件总数、行数、大小、最大文件
现有文档	CLAUDE.md、.ai/ 文件夹、.cursorrules
文件树	项目结构可视化
导入图	Hub 文件、循环依赖、未使用的组件
TypeScript	Props 接口、API 类型、模型类型
测试	测试框架检测、覆盖率映射
安全性	npm audit 漏洞、过时的软件包

输出

生成的 AGENTS.md 包含：

• 简要概览 - 技术栈、组件数量、关键导入、高影响文件
• 快速入门 - 自动生成的设置说明
• 项目概览 - 框架、语言、样式、统计信息
• 关键规则 - 附带错误/正确代码示例
• 组件 - 按类别分组的完整清单
• Hub 文件 - 导入次数最多的文件（更改影响范围广）
• 未使用的组件 - 可能存在死代码的警告
• 首选导入 - 便于代码整洁的 Barrel 导入
• 自定义 Hooks - 带有仅限客户端标记
• API 路由 - 按路径分组，包含方法、身份验证和请求/响应架构
• GraphQL 架构 - 来自 .graphql/.gql 文件的类型定义
• 数据库模型 - 字段和关系
• 环境变量 - 必需与可选变量
• 代码模式 - 检测到的模式及示例
• 设计 Tokens - 颜色 Tokens 及使用指南
• AI 建议 - 根据代码库复杂度推荐模型工作量等级
• 命令 - npm 脚本
• 安全性 - 漏洞和过时的软件包（使用 --security）

输出示例

# 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

关键规则

1. 使用现有组件

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

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

2. 使用设计 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