cursor-compose

Stop hand-writing AI coding rules. Detect your stack, generate them — for every tool.

One command scans your project, detects your frameworks, and writes a tailored rules file. Output a portable AGENTS.md (read by Cursor, Copilot, Codex & Claude Code) or Cursor's native .cursor/rules/*.mdc — from one source.

npx cursor-compose --agents     # → AGENTS.md, works across every major AI editor

---

Why

Everyone is pasting the same recycled rules files between projects. They go stale, they don't match your actual stack, and every editor wants its own format.

cursor-compose reads your real dependencies (package.json, requirements.txt, pubspec.yaml) and composes a rules file from modular, stack-specific building blocks — and writes it as the portable AGENTS.md standard so the same source works in Cursor, Copilot, Codex and Claude Code. Zero config to start.

Usage

# In your project root:
npx cursor-compose            # default → per-module .cursor/rules/*.mdc
npx cursor-compose --agents   # → AGENTS.md (portable, cross-tool)
npx cursor-compose --all      # → both .mdc and AGENTS.md, one pass

It will:

1. Scan your project for dependency files.
2. Show the modules it detected and let you toggle optional ones.
3. Write your chosen output(s).

No install, no config file required.

Flags

Flag	Output
(default)	per-module .cursor/rules/*.mdc (current Cursor format)
--agents	AGENTS.md at repo root — portable across Cursor, Copilot, Codex, Claude Code
--all	both .mdc and AGENTS.md in one pass
--legacy	a single .cursorrules file
--yes, -y	non-interactive: use detected modules, no prompts (great for CI/scripts)
-h, --help	show help

AGENTS.md is safe to hand-edit

The generated content lives between managed markers:

# AGENTS.md
...generated from your stack...

## Your own notes (preserved on regenerate)

Re-running --agents only replaces the managed block — anything you add outside it is kept.

What it detects

Auto-detected	From
Next.js + TypeScript	package.json
Supabase	package.json
Drizzle ORM	package.json
shadcn / Radix UI	package.json
FastAPI	requirements.txt
Flutter	pubspec.yaml

Core conventions always load by default.

Optional modules

Toggle these on during the interactive prompt:

• saas — multi-tenancy, billing, auth patterns
• ecommerce — cart, checkout, payment flows
• claude-code — CLAUDE.md / documentation conventions
• agentic — agent & tool-calling patterns

Requirements

• Node.js 18+

Roadmap

• cursor-compose check — CI command that fails the build when your committed rules drift from your actual dependencies.
• More stacks (Django, Rails, SvelteKit, Expo).

Want a stack supported? Open an issue or send a PR — adding a module is just a markdown file (see CONTRIBUTING.md).

How it works

src/
  cli.js          # interactive prompt + orchestration + flags
  detect.js       # reads dependency files → detected modules
  compose.js      # assembles selected modules; writes .mdc / .cursorrules / AGENTS.md
  frontmatter.js  # Cursor .mdc YAML frontmatter (not used for AGENTS.md)
modules/          # one .md per framework — the rule building blocks
patterns/         # reusable code-organization patterns

Contributing

New modules are welcome and easy — drop a markdown file in modules/. See CONTRIBUTING.md.

License

MIT