<div align="center">

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

</div>

<div align="center">

</div>

---

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: npx @horiastanxd/claude-init check

Example output

<details> <summary><code>CLAUDE.md</code> generated for a Next.js + Prisma app</summary>

# 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 tool
• 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), Python (pip, uv, poetry), Rust (cargo), Go (modules), Java (Maven, Gradle), Ruby (Bundler), and PHP (Composer).

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