claude-init

One command generates the AI context files for every coding assistant - from one repo scan.

CLAUDE.md · AGENTS.md · Cursor · Windsurf · Cline · Continue · Kilo Code · Trae · Copilot · GEMINI.md · Aider · Junie · Warp

npx @horiastanxd/claude-init

Website · npm · Changelog

Why

Every AI coding tool wants a file describing your project - and they all use a different name and format. Keeping over a dozen of them in sync by hand is busywork, and the moment your stack changes they go stale.

claude-init scans your repo once - stack, scripts, structure, env vars, conventions, git - and writes all of them in seconds. No API key, no network, 100% local.

$ npx @horiastanxd/claude-init
✔ Analyzed my-app (TypeScript, Next.js)
  + CLAUDE.md
  + AGENTS.md
  + .cursor/rules/project.mdc
  + .windsurf/rules/project.md
  + .clinerules/project.md
  + .continue/rules/project.md
  + .kilocode/rules/project.md
  + .trae/rules/project_rules.md
  + .github/copilot-instructions.md
  + GEMINI.md
  + CONVENTIONS.md
  + .junie/guidelines.md
  + WARP.md

Done. 13 file(s) generated.

Supported tools

| Target (-t) | File written | Read by | | --- | --- | --- | | claude | CLAUDE.md | Claude Code | | agents | AGENTS.md | OpenAI Codex, Jules, Amp, Zed, Devin, RooCode, Factory, +20 agents | | cursor | .cursor/rules/project.mdc | Cursor (modern .mdc rules) | | windsurf | .windsurf/rules/project.md | Windsurf / Codeium | | cline | .clinerules/project.md | Cline, Roo Code | | continue | .continue/rules/project.md | Continue | | kilocode | .kilocode/rules/project.md | Kilo Code | | trae | .trae/rules/project_rules.md | Trae IDE | | copilot | .github/copilot-instructions.md | GitHub Copilot | | gemini | GEMINI.md | Gemini CLI | | aider | CONVENTIONS.md | Aider | | junie | .junie/guidelines.md | JetBrains Junie | | warp | WARP.md | Warp terminal |

AGENTS.md is becoming the shared standard - one file read by a growing list of agents. claude-init generates it alongside each tool's native format, so you are covered both ways.

Usage

npx @horiastanxd/claude-init                      # generate everything in the current repo
npx @horiastanxd/claude-init ./path/to/repo       # analyze a different directory
npx @horiastanxd/claude-init -t claude,cursor     # only specific tools
npx @horiastanxd/claude-init --overwrite          # refresh files that already exist
npx @horiastanxd/claude-init --dry-run            # print the analysis as JSON, write nothing
npx @horiastanxd/claude-init --recurse            # also generate into each workspace package (monorepo)
npx @horiastanxd/claude-init --enrich             # opt-in: sharpen the description with an LLM (needs ANTHROPIC_API_KEY)
npx @horiastanxd/claude-init list                 # show all targets and their paths

By default existing files are left untouched - re-run with --overwrite to refresh them after your stack changes.

claude-init [generate] [dir]   analyze a repo and write context files (default)
claude-init check [dir]        verify files are up to date (exit 1 on drift)
claude-init list               list supported targets
claude-init mcp                run as an MCP server over stdio

Options:
  -t, --targets <list>   comma-separated target ids, or "all"   (default: all)
  -o, --output <dir>     output directory                        (default: .)
  --overwrite            overwrite existing files
  --dry-run              print the analysis as JSON, write nothing
  --recurse              also generate into each workspace package (monorepo)
  --enrich               use an LLM to enrich the project description (opt-in)
  --enrich-model <model> model for --enrich            (default: claude-opus-4-8)

--enrich is the one feature that leaves your machine, and it is off by default - everything else is 100% local. It needs ANTHROPIC_API_KEY and the Anthropic SDK (npm install @anthropic-ai/sdk); if either is missing, generation continues without enrichment, so nothing breaks.

For a monorepo, --recurse reads the workspaces from package.json (workspaces) or pnpm-workspace.yaml, then generates context files in the root and in each package, analyzing every package on its own. It works for both generate --recurse and check --recurse (and the MCP tools take a recurse flag).

Keep context files fresh

claude-init check regenerates in memory and compares against disk, exiting non-zero on drift. Wire it into CI or a pre-commit hook so your context never rots.

pre-commit (.git/hooks/pre-commit or pre-commit):

npx @horiastanxd/claude-init check || {
  echo "AI context files are stale - run: npx @horiastanxd/claude-init --overwrite"
  exit 1
}

GitHub Actions - run the CLI directly:

- run: npx @horiastanxd/claude-init check

or use the action:

- uses: horiastanxd/claude-init@v1
  with:
    command: check   # or "generate"
    targets: all     # comma-separated ids, or "all"
    # args: --overwrite --recurse

Example output

# my-app

A demo application.

## Stack
- Language: TypeScript
- Framework: Next.js
- Runtime: Node.js
- Package manager: pnpm
- Database: Prisma ORM
- Testing: Vitest

## Commands
```bash
pnpm install   # install
pnpm run dev   # dev
pnpm run test  # test

Code conventions

• TypeScript strict mode is enabled - keep full type safety, avoid any.
• Linter: ESLint. Run it before committing.
• Formatter: Prettier. Do not hand-format against it.

Environment variables

Copy .env.example to .env and set:

• DATABASE_URL (required) - Postgres connection string

</details>

## MCP server

`claude-init` also runs as a [Model Context Protocol](https://modelcontextprotocol.io)
server, so an agent can analyze a repo and write the context files itself.

```bash
# Claude Code
claude mcp add claude-init -- npx @horiastanxd/claude-init --mcp

Tools exposed: analyze_project, generate_context_files, check_context_files.

What gets detected

• Stack - language, framework, runtime, package manager, database, test runner, build / monorepo tool, CI provider
• Commands - install / dev / build / test / lint / format, plus other scripts, Makefile / justfile / Taskfile targets, and commands from .github/workflows
• Structure - a trimmed file tree, entry points, config files
• Conventions - strict mode, linter, formatter, import style, commit convention
• Env vars - parsed from .env.example, with inline comments as descriptions
• Git - default branch, remote, top authors, frequently changed files

Languages: JS/TS (npm, pnpm, yarn, bun), TypeScript on Deno, Python (pip, uv, poetry), Rust (cargo), Go (modules), Java/Kotlin (Maven, Gradle), C#/.NET (NuGet), Elixir (mix), Dart (pub), Ruby (Bundler), and PHP (Composer).

Frameworks detected include Next.js, Remix, Astro, Angular, Gatsby, NestJS, Express, Fastify, Hono, SvelteKit, Nuxt, Vue, Svelte, React (JS/TS); Fresh (Deno); FastAPI, Django, Flask (Python); Axum, Actix, Rocket (Rust); Gin, Fiber, Echo (Go); Spring Boot (Java); ASP.NET Core (.NET); Phoenix (Elixir); Android (Kotlin); Flutter (Dart); Rails, Sinatra (Ruby); and Laravel, Symfony (PHP).

It also recognizes databases (PostgreSQL, MySQL, SQLite, MongoDB, Redis, Supabase, Prisma, Drizzle), monorepo/build tooling (Nx, Turborepo, Lerna, Vite, esbuild, webpack), and the CI provider (GitHub Actions, GitLab CI, CircleCI, Azure Pipelines, Jenkins, Travis, Drone).

Use as a library

import { analyzeProject, generateClaudeMd, buildFiles } from 'claude-init';

const analysis = await analyzeProject(process.cwd());
const md = generateClaudeMd(analysis);

// or render every target in memory
for (const file of buildFiles(analysis)) {
  console.log(file.relPath, file.content.length);
}

Development

npm install
npm run dev -- --dry-run   # run from source
npm test
npm run build

Contributions welcome - adding a new tool is usually a single entry in src/generators/registry.ts. See CONTRIBUTING.md.

Roadmap

• More tools as their formats stabilize

Ideas and PRs welcome.

Star History

License

MIT