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