# ai-rulez ⚡
<p align="center">
<img src="https://raw.githubusercontent.com/Goldziher/ai-rulez/main/docs/assets/logo.png" alt="ai-rulez logo" width="200" style="border-radius: 15%; overflow: hidden;">
</p>
**One config to rule them all.**
## The Problem
If you're using multiple AI coding assistants (Claude Code, Cursor, Windsurf, GitHub Copilot), you've probably noticed the configuration fragmentation. Each tool demands its own format - `CLAUDE.md`, `.cursorrules`, `.windsurfrules`, `.github/copilot-instructions.md`. Keeping coding standards consistent across all these tools is frustrating and error-prone.
## The Solution
AI-Rulez lets you write your project configuration once and automatically generates native files for every AI tool - current and future ones. It's like having a build system for AI context.
<p align="center">
<img src="docs/assets/ai-rulez-python-demo.gif" alt="AI-Rulez Demo" width="100%">
</p>
## Why This Matters
Development teams using AI assistants face common challenges:
- **Multiple tools, multiple configs**: Your team uses Claude Code for reviews, Cursor for development, Copilot for completions
- **Configuration drift**: Maintaining separate files leads to inconsistent standards across tools
- **Monorepo complexity**: Multiple services and packages all need different AI contexts
- **Team consistency**: Junior devs get different AI guidance than seniors
- **Future-proofing**: New AI tools require rewriting all configurations
AI-Rulez solves this with a single `ai-rulez.yaml` that understands your project's conventions.
[](https://go.dev)
[](https://www.npmjs.com/package/ai-rulez)
[](https://pypi.org/project/ai-rulez/)
[](https://github.com/Goldziher/homebrew-tap)
### 📖 **[Read the Full Documentation](https://goldziher.github.io/ai-rulez/)**
---
## Key Features
### AI-Powered Project Analysis
The `init` command is where AI-Rulez shines. Instead of manually writing configurations, let AI analyze your codebase:
```bash
# AI analyzes your codebase and generates tailored config
npx ai-rulez init "My Project" --preset popular --use-agent claude --yes
```
This automatically:
- Detects your tech stack (Python/Node/Go, testing frameworks, linters)
- Identifies project patterns and conventions
- Generates appropriate coding standards and practices
- Creates specialized agents for different tasks (code review, testing, docs)
- **Automatically adds all generated AI files to .gitignore** - no more committing `.cursorrules` or `CLAUDE.md` by accident
### Universal Output Generation
One YAML config generates files for every tool:
- `CLAUDE.md` for Claude Code
- `.cursorrules` for Cursor
- `.windsurfrules` for Windsurf
- `.github/copilot-instructions.md` for GitHub Copilot
- Custom formats for any future AI tool
### Powerful Enterprise Features
- **MCP Integration:** Automatically configure MCP servers across CLI tools (Claude, Gemini) and generate config files for others (Cursor, VS Code). One configuration, every tool connected.
- **Team Collaboration:** Remote config includes, local overrides, and monorepo support with `--recursive`
- **Full-Featured CLI:** Manage your entire configuration from the command line. Add rules, update agents, and generate files without ever opening a YAML file.
- **Security & Performance:** SSRF protection, schema validation, Go-based performance with instant startup
## How It Works
`ai-rulez` takes your `ai-rulez.yml` file and uses it as a single source of truth to generate native configuration files for all your AI tools. Think of it as a build system for AI context—you write the source once, and it compiles to whatever format each tool needs.
## Example: `ai-rulez.yml`
```yaml
$schema: https://github.com/Goldziher/ai-rulez/schema/ai-rules-v2.schema.json
metadata:
name: "My SaaS Platform"
version: "2.0.0"
# Use presets for common configurations
presets:
- "popular" # Includes Claude, Cursor, Windsurf, and Copilot
rules:
- name: "Go Code Standards"
priority: high
content: "Follow standard Go project layout (cmd/, internal/, pkg/). Use meaningful package names and export only what is necessary."
sections:
- name: "Project Structure"
priority: critical
content: |
- `cmd/`: Main application entry point
- `internal/`: Private application code (business logic, data access)
- `pkg/`: Public-facing libraries
agents:
- name: "go-developer"
description: "Go language expert for core development"
system_prompt: "You are an expert Go developer. Your key responsibilities include writing idiomatic Go, using proper error handling, and creating comprehensive tests."
# MCP servers for direct AI tool integration
mcp_servers:
- name: "ai-rulez"
command: "ai-rulez"
args: ["mcp"]
description: "AI-Rulez MCP server for configuration management"
```
Run `ai-rulez generate` → get all your configuration files, perfectly synchronized.
## Quick Start
```bash
# 1. AI-powered initialization (recommended)
ai-rulez init "My Project" --preset popular --use-agent claude
# 2. Generate all AI instruction files
ai-rulez generate
# 3. Your AI tools now have comprehensive, project-specific context!
```
**That's it!** The AI will analyze your codebase and generate tailored rules, documentation, and specialized agents automatically.
**Prefer manual setup?**
```bash
# Basic initialization without AI assistance
ai-rulez init "My Project" --preset popular
# Add your project-specific context
ai-rulez add rule "Tech Stack" --priority critical --content "This project uses Go and PostgreSQL."
# Generate files
ai-rulez generate
```
## MCP Server Integration
`ai-rulez` provides seamless **Model Context Protocol (MCP)** integration, automatically configuring both file-based and CLI-based AI tools with your MCP servers.
### Automatic CLI Configuration
When you run `ai-rulez generate`, MCP servers are **automatically configured** for available CLI tools:
```bash
ai-rulez generate
# ✅ Generated 3 file(s) successfully
# ✅ Configured claude MCP server: ai-rulez
# ✅ Configured gemini MCP server: database-tools
```
**Supported CLI tools:**
- **Claude CLI**: `claude mcp add` with full env/transport support
- **Gemini CLI**: `gemini mcp add` with automatic configuration
### Hybrid Configuration
`ai-rulez` supports both CLI and file-based configurations simultaneously:
```yaml
mcp_servers:
- name: "database-tools"
command: "uvx"
args: ["mcp-server-postgres"]
env:
DATABASE_URL: "postgresql://localhost/mydb"
targets:
- "@claude-cli" # Configure Claude CLI
- "@gemini-cli" # Configure Gemini CLI
- ".cursor/mcp.json" # Generate Cursor config file
```
This single configuration:
- ✅ Executes `claude mcp add` commands
- ✅ Executes `gemini mcp add` commands
- ✅ Generates `.cursor/mcp.json` file
### Control Options
**Default behavior** (recommended):
```bash
ai-rulez generate
# Configures all available CLI tools + generates files
```
**Disable CLI configuration** when needed:
```bash
ai-rulez generate --no-configure-cli-mcp
# Only generates files, skips CLI tool configuration
```
**Target specific tools:**
```yaml
mcp_servers:
- name: "github-integration"
command: "npx"
args: ["@modelcontextprotocol/server-github"]
targets: ["@claude-cli"] # Only configure Claude CLI
```
### Built-in MCP Server
`ai-rulez` includes its own MCP server for configuration management:
```bash
# Start the ai-rulez MCP server
ai-rulez mcp
# Or configure it automatically via your ai-rulez.yaml
mcp_servers:
- name: "ai-rulez"
command: "ai-rulez"
args: ["mcp"]
description: "Configuration management server"
```
## Installation
### Run without installing
For one-off executions, you can run `ai-rulez` directly without a system-wide installation.
**Go**
```bash
go run github.com/Goldziher/ai-rulez/cmd@latest --help
```
**Node.js (via npx)**
```bash
# Installs and runs the latest version
npx ai-rulez@latest init
```
**Python (via uvx)**
```bash
# Runs ai-rulez in a temporary virtual environment
uvx ai-rulez init
```
### Install globally
For frequent use, a global installation is recommended.
**Go**
```bash
go install github.com/Goldziher/ai-rulez/cmd@latest
```
**Homebrew (macOS/Linux)**
```bash
brew install goldziher/tap/ai-rulez
```
**npm**
```bash
npm install -g ai-rulez
```
**pip**
```bash
pip install ai-rulez
```
## Pre-commit Hooks
You can use `ai-rulez` with `pre-commit` to automatically validate and generate your AI configuration files.
Add the following to your `.pre-commit-config.yaml`:
```yaml
repos:
- repo: https://github.com/Goldziher/ai-rulez
rev: v2.1.0
hooks:
- id: ai-rulez-validate
- id: ai-rulez-generate
```
---
## Documentation
- **[Quick Start Guide](https://goldziher.github.io/ai-rulez/quick-start/)**
- **[Full CLI Reference](https://goldziher.github.io/ai-rulez/cli/)**
- **[Configuration Guide](https://goldziher.github.io/ai-rulez/configuration/)**
- **[Migration Guide](https://goldziher.github.io/ai-rulez/migration-guide/)** - Upgrading from v1.x to v2.0
## Contributing
Contributions are welcome! Please see the [Contributing Guide](CONTRIBUTING.md) to get started.
Raw data
{
"_id": null,
"home_page": "https://github.com/Goldziher/ai-rulez",
"name": "ai-rulez",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "ai, ai-assistant, ai-rules, claude, cursor, copilot, windsurf, gemini, cline, continue-dev, mcp, model-context-protocol, cli, configuration, config, rules, generator, golang, go, development, developer-tools, automation, workflow, productivity, pre-commit, git-hooks, code-generation, ai-development, assistant-configuration, monorepo, presets, agents",
"author": "Na'aman Hirschfeld",
"author_email": "nhirschfeld@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/c6/7e/e003638c16261560c7c1ac416f69ffb7901ea8c72f51aba25c0253899955/ai_rulez-2.2.0.tar.gz",
"platform": null,
"description": "# ai-rulez \u26a1\n\n<p align=\"center\">\n <img src=\"https://raw.githubusercontent.com/Goldziher/ai-rulez/main/docs/assets/logo.png\" alt=\"ai-rulez logo\" width=\"200\" style=\"border-radius: 15%; overflow: hidden;\">\n</p>\n\n**One config to rule them all.**\n\n## The Problem\n\nIf you're using multiple AI coding assistants (Claude Code, Cursor, Windsurf, GitHub Copilot), you've probably noticed the configuration fragmentation. Each tool demands its own format - `CLAUDE.md`, `.cursorrules`, `.windsurfrules`, `.github/copilot-instructions.md`. Keeping coding standards consistent across all these tools is frustrating and error-prone.\n\n## The Solution\n\nAI-Rulez lets you write your project configuration once and automatically generates native files for every AI tool - current and future ones. It's like having a build system for AI context.\n\n<p align=\"center\">\n <img src=\"docs/assets/ai-rulez-python-demo.gif\" alt=\"AI-Rulez Demo\" width=\"100%\">\n</p>\n\n## Why This Matters\n\nDevelopment teams using AI assistants face common challenges:\n- **Multiple tools, multiple configs**: Your team uses Claude Code for reviews, Cursor for development, Copilot for completions\n- **Configuration drift**: Maintaining separate files leads to inconsistent standards across tools\n- **Monorepo complexity**: Multiple services and packages all need different AI contexts\n- **Team consistency**: Junior devs get different AI guidance than seniors\n- **Future-proofing**: New AI tools require rewriting all configurations\n\nAI-Rulez solves this with a single `ai-rulez.yaml` that understands your project's conventions.\n\n[](https://go.dev)\n[](https://www.npmjs.com/package/ai-rulez)\n[](https://pypi.org/project/ai-rulez/)\n[](https://github.com/Goldziher/homebrew-tap)\n\n### \ud83d\udcd6 **[Read the Full Documentation](https://goldziher.github.io/ai-rulez/)**\n\n---\n\n## Key Features\n\n### AI-Powered Project Analysis\nThe `init` command is where AI-Rulez shines. Instead of manually writing configurations, let AI analyze your codebase:\n\n```bash\n# AI analyzes your codebase and generates tailored config\nnpx ai-rulez init \"My Project\" --preset popular --use-agent claude --yes\n```\n\nThis automatically:\n- Detects your tech stack (Python/Node/Go, testing frameworks, linters)\n- Identifies project patterns and conventions\n- Generates appropriate coding standards and practices\n- Creates specialized agents for different tasks (code review, testing, docs)\n- **Automatically adds all generated AI files to .gitignore** - no more committing `.cursorrules` or `CLAUDE.md` by accident\n\n### Universal Output Generation\nOne YAML config generates files for every tool:\n- `CLAUDE.md` for Claude Code\n- `.cursorrules` for Cursor\n- `.windsurfrules` for Windsurf \n- `.github/copilot-instructions.md` for GitHub Copilot\n- Custom formats for any future AI tool\n\n### Powerful Enterprise Features\n- **MCP Integration:** Automatically configure MCP servers across CLI tools (Claude, Gemini) and generate config files for others (Cursor, VS Code). One configuration, every tool connected.\n- **Team Collaboration:** Remote config includes, local overrides, and monorepo support with `--recursive`\n- **Full-Featured CLI:** Manage your entire configuration from the command line. Add rules, update agents, and generate files without ever opening a YAML file.\n- **Security & Performance:** SSRF protection, schema validation, Go-based performance with instant startup\n\n## How It Works\n\n`ai-rulez` takes your `ai-rulez.yml` file and uses it as a single source of truth to generate native configuration files for all your AI tools. Think of it as a build system for AI context\u2014you write the source once, and it compiles to whatever format each tool needs.\n\n## Example: `ai-rulez.yml`\n\n```yaml\n$schema: https://github.com/Goldziher/ai-rulez/schema/ai-rules-v2.schema.json\n\nmetadata:\n name: \"My SaaS Platform\"\n version: \"2.0.0\"\n\n# Use presets for common configurations\npresets:\n - \"popular\" # Includes Claude, Cursor, Windsurf, and Copilot\n\nrules:\n - name: \"Go Code Standards\"\n priority: high\n content: \"Follow standard Go project layout (cmd/, internal/, pkg/). Use meaningful package names and export only what is necessary.\"\n\nsections:\n - name: \"Project Structure\"\n priority: critical\n content: |\n - `cmd/`: Main application entry point\n - `internal/`: Private application code (business logic, data access)\n - `pkg/`: Public-facing libraries\n\nagents:\n - name: \"go-developer\"\n description: \"Go language expert for core development\"\n system_prompt: \"You are an expert Go developer. Your key responsibilities include writing idiomatic Go, using proper error handling, and creating comprehensive tests.\"\n\n# MCP servers for direct AI tool integration\nmcp_servers:\n - name: \"ai-rulez\"\n command: \"ai-rulez\"\n args: [\"mcp\"]\n description: \"AI-Rulez MCP server for configuration management\"\n```\n\nRun `ai-rulez generate` \u2192 get all your configuration files, perfectly synchronized.\n\n## Quick Start\n\n```bash\n# 1. AI-powered initialization (recommended)\nai-rulez init \"My Project\" --preset popular --use-agent claude\n\n# 2. Generate all AI instruction files\nai-rulez generate\n\n# 3. Your AI tools now have comprehensive, project-specific context!\n```\n\n**That's it!** The AI will analyze your codebase and generate tailored rules, documentation, and specialized agents automatically.\n\n**Prefer manual setup?**\n```bash\n# Basic initialization without AI assistance\nai-rulez init \"My Project\" --preset popular\n\n# Add your project-specific context \nai-rulez add rule \"Tech Stack\" --priority critical --content \"This project uses Go and PostgreSQL.\"\n\n# Generate files\nai-rulez generate\n```\n\n## MCP Server Integration\n\n`ai-rulez` provides seamless **Model Context Protocol (MCP)** integration, automatically configuring both file-based and CLI-based AI tools with your MCP servers.\n\n### Automatic CLI Configuration\n\nWhen you run `ai-rulez generate`, MCP servers are **automatically configured** for available CLI tools:\n\n```bash\nai-rulez generate\n# \u2705 Generated 3 file(s) successfully\n# \u2705 Configured claude MCP server: ai-rulez\n# \u2705 Configured gemini MCP server: database-tools\n```\n\n**Supported CLI tools:**\n- **Claude CLI**: `claude mcp add` with full env/transport support\n- **Gemini CLI**: `gemini mcp add` with automatic configuration\n\n### Hybrid Configuration\n\n`ai-rulez` supports both CLI and file-based configurations simultaneously:\n\n```yaml\nmcp_servers:\n - name: \"database-tools\"\n command: \"uvx\"\n args: [\"mcp-server-postgres\"]\n env:\n DATABASE_URL: \"postgresql://localhost/mydb\"\n targets: \n - \"@claude-cli\" # Configure Claude CLI\n - \"@gemini-cli\" # Configure Gemini CLI \n - \".cursor/mcp.json\" # Generate Cursor config file\n```\n\nThis single configuration:\n- \u2705 Executes `claude mcp add` commands\n- \u2705 Executes `gemini mcp add` commands \n- \u2705 Generates `.cursor/mcp.json` file\n\n### Control Options\n\n**Default behavior** (recommended):\n```bash\nai-rulez generate\n# Configures all available CLI tools + generates files\n```\n\n**Disable CLI configuration** when needed:\n```bash\nai-rulez generate --no-configure-cli-mcp\n# Only generates files, skips CLI tool configuration\n```\n\n**Target specific tools:**\n```yaml\nmcp_servers:\n - name: \"github-integration\"\n command: \"npx\"\n args: [\"@modelcontextprotocol/server-github\"]\n targets: [\"@claude-cli\"] # Only configure Claude CLI\n```\n\n### Built-in MCP Server\n\n`ai-rulez` includes its own MCP server for configuration management:\n\n```bash\n# Start the ai-rulez MCP server\nai-rulez mcp\n\n# Or configure it automatically via your ai-rulez.yaml\nmcp_servers:\n - name: \"ai-rulez\"\n command: \"ai-rulez\" \n args: [\"mcp\"]\n description: \"Configuration management server\"\n```\n\n## Installation\n\n### Run without installing\n\nFor one-off executions, you can run `ai-rulez` directly without a system-wide installation.\n\n**Go**\n```bash\ngo run github.com/Goldziher/ai-rulez/cmd@latest --help\n```\n\n**Node.js (via npx)**\n```bash\n# Installs and runs the latest version\nnpx ai-rulez@latest init\n```\n\n**Python (via uvx)**\n```bash\n# Runs ai-rulez in a temporary virtual environment\nuvx ai-rulez init\n```\n\n### Install globally\n\nFor frequent use, a global installation is recommended.\n\n**Go**\n```bash\ngo install github.com/Goldziher/ai-rulez/cmd@latest\n```\n\n**Homebrew (macOS/Linux)**\n```bash\nbrew install goldziher/tap/ai-rulez\n```\n\n**npm**\n```bash\nnpm install -g ai-rulez\n```\n\n**pip**\n```bash\npip install ai-rulez\n```\n\n## Pre-commit Hooks\n\nYou can use `ai-rulez` with `pre-commit` to automatically validate and generate your AI configuration files.\n\nAdd the following to your `.pre-commit-config.yaml`:\n\n```yaml\nrepos:\n - repo: https://github.com/Goldziher/ai-rulez\n rev: v2.1.0\n hooks:\n - id: ai-rulez-validate\n - id: ai-rulez-generate\n```\n\n---\n\n## Documentation\n\n- **[Quick Start Guide](https://goldziher.github.io/ai-rulez/quick-start/)**\n- **[Full CLI Reference](https://goldziher.github.io/ai-rulez/cli/)**\n- **[Configuration Guide](https://goldziher.github.io/ai-rulez/configuration/)**\n- **[Migration Guide](https://goldziher.github.io/ai-rulez/migration-guide/)** - Upgrading from v1.x to v2.0\n\n## Contributing\n\nContributions are welcome! Please see the [Contributing Guide](CONTRIBUTING.md) to get started.\n",
"bugtrack_url": null,
"license": null,
"summary": "\u26a1 One config to rule them all. Centralized AI assistant configuration management - generate rules for Claude, Cursor, Copilot, Windsurf and more from a single YAML file.",
"version": "2.2.0",
"project_urls": {
"Bug Reports": "https://github.com/Goldziher/ai-rulez/issues",
"Changelog": "https://github.com/Goldziher/ai-rulez/releases",
"Documentation": "https://goldziher.github.io/ai-rulez/",
"Funding": "https://github.com/sponsors/Goldziher",
"Homepage": "https://goldziher.github.io/ai-rulez/",
"Source": "https://github.com/Goldziher/ai-rulez"
},
"split_keywords": [
"ai",
" ai-assistant",
" ai-rules",
" claude",
" cursor",
" copilot",
" windsurf",
" gemini",
" cline",
" continue-dev",
" mcp",
" model-context-protocol",
" cli",
" configuration",
" config",
" rules",
" generator",
" golang",
" go",
" development",
" developer-tools",
" automation",
" workflow",
" productivity",
" pre-commit",
" git-hooks",
" code-generation",
" ai-development",
" assistant-configuration",
" monorepo",
" presets",
" agents"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "99d69967189784780410be8cefb4cf074958946866eb7e1228102634eaaa45a8",
"md5": "870b28eae408a100dafbb1c4820929ca",
"sha256": "18df68e1208fdd84779a82c490d57810852b318a1f45eb0ec3d07a816ea58c1c"
},
"downloads": -1,
"filename": "ai_rulez-2.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "870b28eae408a100dafbb1c4820929ca",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 9510,
"upload_time": "2025-09-11T10:11:57",
"upload_time_iso_8601": "2025-09-11T10:11:57.384872Z",
"url": "https://files.pythonhosted.org/packages/99/d6/9967189784780410be8cefb4cf074958946866eb7e1228102634eaaa45a8/ai_rulez-2.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c67ee003638c16261560c7c1ac416f69ffb7901ea8c72f51aba25c0253899955",
"md5": "933c668c5d7d63996dbf60db97db05db",
"sha256": "1a86a8697d54c672ea6ce4a664e7794ff33637f8d53b4e08ecee40be47d2e69e"
},
"downloads": -1,
"filename": "ai_rulez-2.2.0.tar.gz",
"has_sig": false,
"md5_digest": "933c668c5d7d63996dbf60db97db05db",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 13658,
"upload_time": "2025-09-11T10:11:58",
"upload_time_iso_8601": "2025-09-11T10:11:58.657181Z",
"url": "https://files.pythonhosted.org/packages/c6/7e/e003638c16261560c7c1ac416f69ffb7901ea8c72f51aba25c0253899955/ai_rulez-2.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-11 10:11:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Goldziher",
"github_project": "ai-rulez",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ai-rulez"
}
JSON
