codespec

codespec

Auto-generate AI coding assistant configs by deep-analyzing your codebase.

Stop writing CLAUDE.md, .cursorrules, and Copilot instructions by hand. Run one command and get config files with evidence-based rules from your actual code.

npx codespec init

  codespec v2 - AI config generator with deep code analysis
  -----------------------------------------

  Analysis complete

  Project:     my-app
  Language:    typescript
  Framework:   Next.js v15.2
  Styling:     Tailwind CSS
  ORM:         Prisma
  Testing:     Vitest

  Code Analysis:
  Functions:   143
  Classes:     8
  Avg Length:  18 lines
  Naming:      camelCase (92%)

  Generated:
    + CLAUDE.md
    + .cursorrules
    + .github/copilot-instructions.md

What's different?

Most config generators give you generic rules like "This is a Next.js project. Use App Router."

codespec actually reads your code and gives you evidence-based rules:

## Code Patterns (from analysis)

- Functions use **camelCase** naming (143 of 155 functions, 92%)
- Error handling: **try/catch (15 blocks) + 3 custom error classes**
- Async pattern: **47 async/await, 0 .then() callbacks**
- Average function length: **18 lines**
- Max cyclomatic complexity: **8**
- TypeScript types: 25 interfaces, 18 type aliases, **0 `any` usage**
- React hooks: useState (34x), useEffect (21x)

## Top Dependencies

- `@prisma/client` imported in 23 files
- `zod` imported in 18 files
- `next/navigation` imported in 12 files

Every rule comes with proof. Real numbers from your codebase, not guesses.

Why?

Every AI coding assistant works better with project context. But writing config files by hand is tedious and they go stale fast.

codespec reads your actual codebase — functions, classes, imports, error patterns, async usage, naming conventions — and generates configs that match what's really there.

No files leave your machine. Everything runs locally.

What it generates

File	For	What it includes
CLAUDE.md	Claude Code	Project overview, code patterns with metrics, top dependencies, API routes, dev commands, evidence-based rules
.cursorrules	Cursor	Role definition, code insights, coding standards, framework guidelines, error handling patterns
.github/copilot-instructions.md	GitHub Copilot	Code generation instructions, test generation rules, review guidelines — all evidence-based

Install

# Run directly (no install needed)
npx codespec init

# Or install globally
npm install -g codespec

Usage

# Generate all configs for current directory
codespec init

# Generate only specific configs
codespec init --claude
codespec init --cursor
codespec init --copilot

# Preview without writing files
codespec init --dry-run

# Show detailed code analysis
codespec init --verbose

# Scan a different directory
codespec init ./path/to/project

# Update existing configs (preserves your custom sections)
codespec update

# Show diff between existing and newly generated configs
codespec diff

What it detects

Project-level detection

Category	Details
Languages	TypeScript, JavaScript, Python, Go, Rust, Java, Ruby, PHP, Swift, Kotlin, C#
Frameworks	Next.js, React, Vue, Nuxt, Svelte, Angular, Remix, Astro, Express, Fastify, NestJS, Hono, Django, FastAPI, Flask, Rails, Laravel, Spring Boot, Gin, Echo, Fiber, Actix, Axum
Package managers	npm, yarn, pnpm, bun, pip, poetry, cargo, go modules
ORMs	Prisma, Drizzle, TypeORM, Sequelize, SQLAlchemy, Django ORM
Styling	Tailwind CSS, styled-components, CSS Modules, Sass, Emotion
State	Redux, Zustand, Jotai, MobX, Pinia, Vuex
Testing	Jest, Vitest, Pytest, Playwright, Cypress
Linting	ESLint, Biome, Prettier, Ruff, Black
Infra	Docker, Vercel, Railway, Fly.io, Netlify

Code-level analysis

Metric	What it finds
Functions	Count, names, line length, async/sync, exported or not
Classes	Count, method names, exported or not
Naming conventions	camelCase vs snake_case vs PascalCase with percentages
Error handling	try/catch count, custom error classes
Async patterns	async/await vs .then() vs new Promise
Type usage	any count, unknown, interfaces, type aliases
Complexity	Cyclomatic complexity per function
React hooks	Which hooks are used and how often
API routes	Next.js, Express, FastAPI, Flask, Django route detection
Dependencies	Most imported packages ranked by frequency

Commands

Command	Description
codespec init	Analyze codebase and generate config files
codespec analyze	Analyze only (no file generation)
codespec update	Update existing configs with fresh analysis (preserves custom sections)
codespec diff	Show diff between existing and newly generated configs

Flags

Flag	Description
--claude	Generate only CLAUDE.md
--cursor	Generate only .cursorrules
--copilot	Generate only copilot-instructions.md
--dry-run	Preview without writing files
--verbose	Show detailed code analysis output

Contributing

PRs welcome! Especially for:

• New language support — add extraction patterns in src/parser/
• Better code analysis — improve extractors in src/parser/extractors.ts
• New framework detection — add patterns in src/analyzer/framework.ts
• New AI tools — add generators for Windsurf, Cody, etc.

License

MIT