airulegen

One command. Every AI coding tool. Zero config.

Auto-scan your project and generate optimized rule files for Claude, Cursor, Copilot, Windsurf, and 9 more tools.

Stop manually writing .cursorrules, CLAUDE.md, .windsurfrules for every project. airulegen scans your tech stack and generates them all — instantly.

npx airulegen init

$ npx airulegen init

✔ Project scanned

Detected Stack:
  Language:        typescript
  Framework:       nextjs
  Package Manager: pnpm
  Styling:         tailwind
  Testing:         vitest
  ORM:             prisma

Matched Presets:
  ✓ general
  ✓ typescript
  ✓ nextjs
  ✓ react

✔ Generated 11 rule files

  ✓ CLAUDE.md
  ✓ .cursor/rules/airules.mdc
  ✓ .windsurfrules
  ✓ .github/copilot-instructions.md
  ✓ .clinerules
  ✓ AGENTS.md
  ✓ GEMINI.md
  ✓ CONVENTIONS.md
  ✓ .rules
  ✓ .roo/rules/airules.md
  ✓ .amazonq/rules/airules.md
  ✓ .airules.yaml

Why airules?

You're using AI coding assistants. So is your team. But each tool needs its own config file in its own format — and writing good rules by hand is tedious, inconsistent, and usually gets skipped.

airules fixes this. One scan. One config. Every tool gets optimized rules, tailored to your actual stack.

| Problem | Without airules | With airules | |---------|----------------|-------------| | New project setup | Manually write rules for each AI tool | npx airulegen init — done in 2 seconds | | Team consistency | Everyone has different rules (or none) | Commit generated files — whole team benefits | | Adding a new AI tool | Copy-paste and adapt from another tool's format | npx airulegen sync — regenerate all | | Framework best practices | Google it, hope the AI follows it | Built-in presets with battle-tested rules |

Supported Tools

| Tool | Output File | Format | |------|-----------|--------| | Claude Code | CLAUDE.md | Markdown | | Cursor | .cursor/rules/airules.mdc | YAML frontmatter + Markdown | | GitHub Copilot | .github/copilot-instructions.md | Markdown | | Windsurf | .windsurfrules | Markdown | | Cline | .clinerules | Markdown | | OpenAI Codex | AGENTS.md | Markdown | | OpenCode | AGENTS.md | Markdown | | Gemini | GEMINI.md | Markdown | | Aider | CONVENTIONS.md | Markdown | | Zed | .rules | Markdown | | Roo Code | .roo/rules/airules.md | YAML frontmatter + Markdown | | Amazon Q | .amazonq/rules/airules.md | Markdown |

Supported Frameworks

Auto-detected from your project. Zero config required.

| Preset | Detects | Rules Include | |--------|---------|---------------| | General | All projects | Code style, error handling, security, git conventions | | TypeScript | tsconfig.json | Type safety, patterns, imports, error handling | | Next.js | next in deps | App Router, data fetching, routing, performance | | React | react in deps | Components, hooks, state management, patterns | | Vue | vue in deps | Composition API, SFC, composables | | Express | express in deps | Middleware, routing, security | | FastAPI | fastapi in deps | Pydantic, dependency injection, async patterns | | Django | django in deps | Models, views, ORM, security | | Go | go.mod | Error handling, interfaces, project structure | | Rust | Cargo.toml | Ownership, error handling, patterns |

How It Works

1. SCAN        Your project's package.json, tsconfig, go.mod, etc.
               Detects: language, framework, dependencies, structure
                                    ↓
2. MATCH       Auto-selects relevant presets (e.g., TypeScript + Next.js + React)
               Generates framework-specific, actionable rules
                                    ↓
3. EMIT        Writes correctly formatted files for each AI tool
               CLAUDE.md, .cursorrules, .windsurfrules, AGENTS.md, etc.

Quick Start

Generate rules for all tools

npx airulegen init

Generate for specific tools only

npx airulegen init --tools claude,cursor,copilot

Preview without writing files

npx airulegen init --dry-run

Regenerate from existing config

npx airulegen sync

List available presets and tools

npx airulegen list

Configuration

After running init, airules creates .airules.yaml in your project root:

# Generated by airules. Customize as needed.
version: 1

tools:
  - claude
  - cursor
  - copilot
  - windsurf
  - cline
  - codex
  - gemini
  - aider
  - zed
  - roo
  - amazonq

presets:
  - general
  - typescript
  - nextjs
  - react

detected:
  language: typescript
  framework: nextjs
  packageManager: pnpm
  styling: tailwind
  testing: vitest
  orm: prisma

# Add custom rules
custom:
  - title: "Project Conventions"
    content: |
      - Use pnpm for package management
      - All API routes must use zod validation

Edit this file, then run npx airulegen sync to regenerate.

What Makes the Rules Good?

Unlike generic "write clean code" advice, airules generates specific, actionable rules that AI assistants can actually follow:

## Type Safety

- **Never use `any`** — use `unknown` and narrow with type guards
- **Never use `@ts-ignore` or `@ts-expect-error`** — fix the underlying type error
- Prefer `interface` for object shapes, `type` for unions/intersections
- Use `readonly` for immutable data
- Always type exported function params and return types
- Use discriminated unions over type assertions

## Next.js App Router

- Use Server Components by default — only add `'use client'` when you need
  browser APIs, event handlers, or React hooks
- Use `page.tsx`, `layout.tsx`, `loading.tsx`, `error.tsx` naming conventions
- Fetch data in Server Components, not with `useEffect`
- Use Server Actions for mutations instead of API routes

Every rule is something an AI can follow immediately. No fluff.

vs Alternatives

| Feature | airules | dotagent | rulebook-ai | |---------|:-----------:|:--------:|:-----------:| | Auto-scan project | Yes | No | No | | Generate rules from scratch | Yes | No | No | | Convert between formats | Planned | Yes | Yes | | Zero config | Yes | No | No | | Tools supported | 13 | 15 | 8 | | Framework presets | 10 | 0 | 0 | | Language | TypeScript | TypeScript | Python | | One command | npx airulegen init | Manual config | pip install + config |

Programmatic API

import { generate, scanProject } from 'airulegen';

// Scan a project
const scan = await scanProject('./my-project');

// Generate rule files
const result = await generate({
  projectRoot: './my-project',
  tools: ['claude', 'cursor'],
});

// result.emitResults contains { path, content } for each file
for (const file of result.emitResults) {
  console.log(file.path, file.content.length);
}

Contributing

Contributions are welcome! Areas where help is most needed:

• New presets — Add rules for Ruby/Rails, PHP/Laravel, Svelte, Angular, etc.
• New emitters — Support additional AI coding tools
• Rule quality — Improve existing preset rules based on real-world experience
• Testing — More edge cases, E2E tests

# Clone and setup
git clone https://github.com/deepdevy/airules.git
cd airules
npm install

# Dev workflow
npm run dev        # watch mode
npm test           # run tests
npm run build      # production build

License

MIT

If this saved you time, consider giving it a ⭐

Report Bug · Request Feature · Discussions