ai-rules-generator 1.0.0

A CLI tool that generates comprehensive AI coding agent rules for Cursor and Claude Code

AI Rules Generator

A CLI tool that generates comprehensive AI coding agent rules for Cursor and Claude Code based on your project configuration and best practices.

Features

• Interactive Setup: Configure once, use everywhere - no shell config editing needed!
• Multi-Tool Support: Generates rule files for 6 AI coding tools (Cursor, Claude Code, Windsurf, GitHub Copilot, Warp, Janie)
• Shared AI Rules: Creates .ai-rules/ directory - single source of truth referenced by all tools
• Multiple AI Providers: Support for OpenAI and Anthropic Claude models
• Monorepo Support: Automatically detects and generates rules for each package
• Language & Framework Specific: Tailored rules for 20+ languages and 100+ frameworks
• Template Fallback: Works even without AI API keys using template-based generation

Quick Start

1. Install

Choose your preferred package manager:

macOS (Homebrew):

brew tap rpupo63/ai-rules-generator
brew install ai-rules-generator

Arch Linux (AUR):

yay -S ai-rules-generator

Debian/Ubuntu (APT):

sudo apt install ai-rules-generator

Linux (Flatpak):

flatpak install flathub com.github.ai_rules_generator.AIRulesGenerator

Windows (Chocolatey):

choco install ai-rules-generator

Windows (WinGet): Coming in v1.0.1 - Use Chocolatey for now

Any Platform (pip):

pip install ai-rules-generator

2. Configure (One-Time Setup)

Run the interactive setup:

ai-rules-generator init

This will:

• Let you choose your AI provider (OpenAI, Anthropic, or None)
• Let you select a model
• Store your API keys securely in the config file
• Let you choose which AI coding tools you use

No need to modify .bashrc, .zshrc, or PowerShell profile! Everything is stored in:

• Linux: ~/.config/ai-rules-generator/config.json
• macOS: ~/Library/Application Support/ai-rules-generator/config.json
• Windows: %APPDATA%\ai-rules-generator\config.json

3. Generate Rules for Your Project

Navigate to your project and run:

cd /path/to/your/project
ai-rules-generator project-init

Done! Your project now has AI rules configured for all your selected AI coding tools.

Installation Details

Homebrew (macOS/Linux)

# Add the tap (first time only)
brew tap rpupo63/ai-rules-generator

# Install
brew install ai-rules-generator

# Update
brew upgrade ai-rules-generator

AUR (Arch Linux)

# Using yay
yay -S ai-rules-generator

# Or using paru
paru -S ai-rules-generator

# Update
yay -Syu ai-rules-generator

APT (Debian/Ubuntu)

# Add PPA (first time only)
sudo add-apt-repository ppa:rpupo63/ai-rules-generator
sudo apt update

# Install
sudo apt install ai-rules-generator

# Update
sudo apt update && sudo apt upgrade ai-rules-generator

Or install from .deb file:

wget https://github.com/rpupo63/ai-rules-generator/releases/download/v1.0.0/ai-rules-generator_1.0.0-1_all.deb
sudo apt install ./ai-rules-generator_1.0.0-1_all.deb

Flatpak (Linux - Universal)

# Install from Flathub
flatpak install flathub com.github.ai_rules_generator.AIRulesGenerator

# Run
flatpak run com.github.ai_rules_generator.AIRulesGenerator

# Update
flatpak update com.github.ai_rules_generator.AIRulesGenerator

Chocolatey (Windows)

# Install
choco install ai-rules-generator

# Update
choco upgrade ai-rules-generator

winget (Windows)

# Install
winget install AIRulesGenerator.AIRulesGenerator

# Update
winget upgrade AIRulesGenerator.AIRulesGenerator

pip (All Platforms)

# Install from PyPI
pip install ai-rules-generator

# Install with AI provider support
pip install ai-rules-generator[all]        # Both OpenAI and Anthropic
pip install ai-rules-generator[openai]     # OpenAI only
pip install ai-rules-generator[anthropic]  # Anthropic only

# Update
pip install --upgrade ai-rules-generator

# Install from source (development)
git clone https://github.com/rpupo63/ai-rules-generator.git
cd ai-rules-generator
pip install -e .[all]

Usage

Available Commands

# Global configuration (one-time setup)
ai-rules-generator init              # Interactive setup
ai-rules-generator config show       # View current configuration
ai-rules-generator config edit       # Edit configuration
ai-rules-generator config reset      # Reset to defaults

# Project-level commands
ai-rules-generator project-init      # Initialize rules for current project

Or use the shorter alias:

ai-rules init
ai-rules project-init

Configuration Management

The init command provides an interactive setup. You can also manage configuration manually:

# Set AI provider
ai-rules-generator config set provider openai

# Set AI model
ai-rules-generator config set model gpt-4o

# Set API keys
ai-rules-generator config set openai-key sk-...
ai-rules-generator config set anthropic-key sk-ant-...

# Set enabled tools (comma-separated)
ai-rules-generator config set enabled-tools cursor,claude-code,windsurf

What Gets Generated

After running project-init, your project will have:

Shared Rules (always created):

• .ai-rules/ - Directory with organized rule files
  • project-rules.md - Main project rules
  • language-*.md - Language-specific best practices
  • framework-*.md - Framework-specific rules
  • universal-*.md - Universal best practices
  • README.md - Index of all rule files

Tool-Specific Files (based on your selection):

• Cursor: .cursorrules + .cursor/rules/*.mdc
• Claude Code: CLAUDE.md + .claude/rules/
• Windsurf: .windsurfrules
• GitHub Copilot: .github/copilot-instructions.md
• Warp: .warp/rules.md
• Janie: .janie/rules.md

All tool files reference the shared .ai-rules/ directory, keeping rules DRY and maintainable.

Supported AI Coding Tools

The tool supports 6 AI coding tools. During init, select which tools you use:

1. Cursor - .cursorrules + .cursor/rules/*.mdc files
2. Claude Code - CLAUDE.md + .claude/rules/ directory
3. Windsurf - .windsurfrules file
4. GitHub Copilot - .github/copilot-instructions.md
5. Warp - .warp/rules.md file
6. Janie - .janie/rules.md file

To change which tools are enabled:

ai-rules-generator config edit

Supported Languages

Python, TypeScript, JavaScript, Rust, C++, Java, Go, Kotlin, Swift, Elixir, PHP, Ruby, Scala, R, Solidity, HTML, CSS, and more.

Supported Frameworks

100+ frameworks including:

• Python: FastAPI, Django, Flask, Temporal
• TypeScript/JavaScript: Next.js, React, Vue, Svelte, Angular, Astro, Node.js
• And many more...

During interactive mode, you'll see framework options specific to your selected language.

AI Providers

OpenAI

• gpt-4o (recommended)
• gpt-4o-mini (faster, cheaper)
• gpt-4-turbo
• gpt-4
• gpt-3.5-turbo

Anthropic Claude

• claude-3-5-sonnet-20241022 (recommended)
• claude-3-5-haiku-20241022 (faster)
• claude-3-opus-20240229
• claude-3-sonnet-20240229
• claude-3-haiku-20240307

None (Template-based)

Use template-based generation without AI API calls.

API Key Management

API keys are stored securely in the config file. No need to manually edit environment variables!

Storing API Keys

Option 1: Interactive setup (recommended)

ai-rules-generator init
# Enter API keys when prompted

Option 2: Command line

ai-rules-generator config set openai-key sk-...
ai-rules-generator config set anthropic-key sk-ant-...

Option 3: Environment variables (optional)

export OPENAI_API_KEY='sk-...'
export ANTHROPIC_API_KEY='sk-ant-...'

Environment variables take precedence if set, but the config file is more convenient.

Security Note

• Config file is stored with user-only read/write permissions
• API keys are stored as plain text in the config file
• Both config file and environment variables have similar security profiles
• Use --show-keys flag cautiously when displaying configuration

Examples

Single Project Setup

# One-time global setup
ai-rules-generator init

# In your project
cd my-fastapi-project
ai-rules-generator project-init

Monorepo Setup

# One-time global setup
ai-rules-generator init

# In your monorepo root
cd my-monorepo
ai-rules-generator project-init
# Automatically detects packages and creates rules for each

Template-based (No API Key)

# Configure to use template mode
ai-rules-generator init
# Select: none -> template

# Generate rules without AI
cd my-project
ai-rules-generator project-init

Configuration File

Your configuration is stored in a platform-appropriate location:

Linux:

~/.config/ai-rules-generator/config.json

macOS:

~/Library/Application Support/ai-rules-generator/config.json

Windows:

%APPDATA%\ai-rules-generator\config.json

Example config:

{
  "ai_provider": "openai",
  "ai_model": "gpt-4o-mini",
  "openai_api_key": "sk-...",
  "anthropic_api_key": null,
  "enabled_tools": ["cursor", "claude-code", "windsurf"]
}

Troubleshooting

Command not found after installation

Make sure your PATH includes the installation directory:

• pip: ~/.local/bin (Linux/macOS) or %APPDATA%\Python\Scripts (Windows)
• Homebrew: /usr/local/bin (Intel) or /opt/homebrew/bin (Apple Silicon)

Config file location

View your config path:

python -c "from ai_rules_generator.config_manager import get_config_path; print(get_config_path())"

Reset configuration

ai-rules-generator config reset
ai-rules-generator init

Contributing

Contributions welcome! Please read DEVELOPMENT.md for development setup and publishing instructions.

License

MIT

Credits

Built using best practices from awesome-cursorrules.

Links

• 📖 Documentation: This README
• 🐛 Issues: https://github.com/rpupo63/ai-rules-generator/issues
• 💬 Discussions: https://github.com/rpupo63/ai-rules-generator/discussions
• 📦 PyPI: https://pypi.org/project/ai-rules-generator/
• 🍺 Homebrew: brew tap rpupo63/ai-rules-generator
• 🐧 AUR: https://aur.archlinux.org/packages/ai-rules-generator
• 📦 Debian/Ubuntu PPA: ppa:rpupo63/ai-rules-generator
• 📦 Flatpak: https://flathub.org/apps/com.github.ai_rules_generator.AIRulesGenerator
• 🪟 Chocolatey: https://community.chocolatey.org/packages/ai-rules-generator
• 🪟 winget: winget install AIRulesGenerator.AIRulesGenerator