# ai-rulez ⚡
> **Lightning-fast CLI tool (written in Go) for managing AI assistant rules**
Generate configuration files for Claude, Cursor, Windsurf, and other AI assistants from a single, centralized configuration.
## 🚀 Features
- ⚡ **Blazing Fast**: Written in Go for maximum performance
- 🔧 **Multi-Assistant Support**: Generate configs for Claude (CLAUDE.md), Cursor (.cursorrules), Windsurf (.windsurfrules), and more
- 📝 **Single Source of Truth**: Maintain all your AI rules in one YAML configuration
- 🎯 **Smart Templates**: Built-in templates with custom template support
- 🔍 **Validation**: Comprehensive configuration validation
- 🔄 **Git Integration**: Perfect for pre-commit hooks and CI/CD
- 🐍 **Python Integration**: Easy installation via pip
## 📦 Installation
### pip (Recommended)
```bash
pip install ai-rulez
```
The Python package automatically downloads and manages the Go binary for your platform.
### Other Installation Methods
- **npm**: `npm install -g ai-rulez`
- **Go**: `go install github.com/Goldziher/ai-rulez@latest`
- **Homebrew**: `brew install goldziher/tap/ai-rulez` *(coming soon)*
- **Direct Download**: Download from [GitHub Releases](https://github.com/Goldziher/ai-rulez/releases)
## 🎯 Quick Start
1. **Create a configuration file** (`ai-rulez.yaml`):
```yaml
metadata:
name: "My AI Rules"
version: "1.0.0"
rules:
- name: "Code Style"
priority: 10
content: |
- Use TypeScript strict mode
- Prefer functional components
- Use meaningful variable names
- name: "Testing"
priority: 5
content: |
- Write unit tests for all functions
- Use describe/it pattern
- Aim for 80% code coverage
outputs:
- file: "CLAUDE.md"
template: "claude"
- file: ".cursorrules"
template: "cursor"
- file: ".windsurfrules"
template: "windsurf"
```
2. **Generate configuration files**:
```bash
ai-rulez generate
```
This creates `CLAUDE.md`, `.cursorrules`, and `.windsurfrules` with your rules properly formatted for each AI assistant.
## 🛠️ Commands
```bash
# Generate all configuration files
ai-rulez generate
# Validate configuration
ai-rulez validate
# Generate recursively in subdirectories
ai-rulez generate --recursive
# Preview output without writing files
ai-rulez generate --dry-run
# Show help
ai-rulez --help
```
## 🔄 Git Integration
### Pre-commit Hook
Add to your `.pre-commit-config.yaml`:
```yaml
repos:
- repo: https://github.com/Goldziher/ai-rulez
rev: v1.0.0
hooks:
- id: ai-rulez-generate
```
### Lefthook
Add to your `lefthook.yml`:
```yaml
pre-commit:
commands:
ai-rulez:
run: ai-rulez generate
files: git diff --cached --name-only
glob: "*.{ai-rulez,ai_rulez}.{yml,yaml}"
```
## 📚 Configuration
The tool looks for configuration files in this order:
- `.ai-rulez.yaml`
- `ai-rulez.yaml`
- `.ai_rulez.yaml`
- `ai_rulez.yaml`
### User Rules vs. Coding Rules
When creating AI rules, distinguish between two types of instructions:
- **Coding Rules**: Technical guidelines about code quality, architecture, testing, etc.
- Examples: "Use TypeScript strict mode", "Write unit tests", "Follow REST conventions"
- Should be in the main configuration file committed to version control
- **User Rules**: Personal preferences about communication style and interaction
- Examples: "Be concise in responses", "Use casual tone", "Address me as 'Chief'", "Always explain your reasoning"
- Perfect for `.local.yaml` files (e.g., `ai-rulez.local.yaml`) as they're personal and shouldn't affect the whole team
- Allow individual developers to customize AI behavior without impacting others
**Example local config** (`ai-rulez.local.yaml`):
```yaml
rules:
- name: "Communication Style"
content: "Be concise and direct. Address me as 'Boss'. Always ask for clarification before making assumptions."
- name: "Response Format"
content: "Provide code examples for every suggestion. Use bullet points for lists."
```
### Configuration Schema
```yaml
metadata:
name: string # Required: Project name
version: string # Required: Version
description: string # Optional: Description
rules:
- name: string # Required: Rule name
priority: number # Required: Priority (1-10)
content: string # Required: Rule content
sections: # Optional: Organize rules into sections
- title: string # Required: Section title
priority: number # Required: Section priority
content: string # Required: Section content
outputs: # Required: At least one output
- file: string # Required: Output filename
template: string # Required: Template name or path
includes: # Optional: Include other config files
- path/to/other.yaml
```
## 🎨 Templates
Built-in templates:
- `claude` - CLAUDE.md format
- `cursor` - .cursorrules format
- `windsurf` - .windsurfrules format
- `default` - Generic format
Custom templates use Go template syntax with access to `.Rules`, `.Sections`, `.Metadata`, etc.
## 🔧 Advanced Usage
### Environment Variables
- `AI_RULEZ_CONFIG` - Override config file path
- `AI_RULEZ_DEBUG` - Enable debug output
### Python API
```python
from ai_rulez.cli import main
import sys
# Run ai-rulez programmatically
sys.argv = ['ai-rulez', 'generate', '--dry-run']
main()
```
## 🤝 Contributing
Contributions are welcome! Please see our [Contributing Guide](https://github.com/Goldziher/ai-rulez/blob/main/CONTRIBUTING.md).
## 📄 License
MIT License - see [LICENSE](https://github.com/Goldziher/ai-rulez/blob/main/LICENSE)
## 🔗 Links
- [GitHub Repository](https://github.com/Goldziher/ai-rulez)
- [Documentation](https://github.com/Goldziher/ai-rulez#readme)
- [Issues](https://github.com/Goldziher/ai-rulez/issues)
- [Releases](https://github.com/Goldziher/ai-rulez/releases)
- [npm Package](https://www.npmjs.com/package/ai-rulez)
---
**Note**: This Python package is a wrapper around the Go binary. The actual tool is written in Go for maximum performance and cross-platform compatibility.
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, windsurf, codeium, copilot, cli, cli-tool, configuration, config, rules, generator, golang, fast, development, developer-tools, automation, workflow, productivity, pre-commit, git-hooks, lefthook, code-generation, ai-development, assistant-configuration",
"author": "Na'aman Hirschfeld",
"author_email": "nhirschfeld@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/79/f9/c23ee69e245cbde2171f01fcd9b496f90b89afea1580998a4b4135ad6edf/ai_rulez-1.1.4.tar.gz",
"platform": null,
"description": "# ai-rulez \u26a1\n\n> **Lightning-fast CLI tool (written in Go) for managing AI assistant rules**\n\nGenerate configuration files for Claude, Cursor, Windsurf, and other AI assistants from a single, centralized configuration.\n\n## \ud83d\ude80 Features\n\n- \u26a1 **Blazing Fast**: Written in Go for maximum performance\n- \ud83d\udd27 **Multi-Assistant Support**: Generate configs for Claude (CLAUDE.md), Cursor (.cursorrules), Windsurf (.windsurfrules), and more\n- \ud83d\udcdd **Single Source of Truth**: Maintain all your AI rules in one YAML configuration\n- \ud83c\udfaf **Smart Templates**: Built-in templates with custom template support\n- \ud83d\udd0d **Validation**: Comprehensive configuration validation\n- \ud83d\udd04 **Git Integration**: Perfect for pre-commit hooks and CI/CD\n- \ud83d\udc0d **Python Integration**: Easy installation via pip\n\n## \ud83d\udce6 Installation\n\n### pip (Recommended)\n\n```bash\npip install ai-rulez\n```\n\nThe Python package automatically downloads and manages the Go binary for your platform.\n\n### Other Installation Methods\n\n- **npm**: `npm install -g ai-rulez`\n- **Go**: `go install github.com/Goldziher/ai-rulez@latest`\n- **Homebrew**: `brew install goldziher/tap/ai-rulez` *(coming soon)*\n- **Direct Download**: Download from [GitHub Releases](https://github.com/Goldziher/ai-rulez/releases)\n\n## \ud83c\udfaf Quick Start\n\n1. **Create a configuration file** (`ai-rulez.yaml`):\n\n```yaml\nmetadata:\n name: \"My AI Rules\"\n version: \"1.0.0\"\n\nrules:\n - name: \"Code Style\"\n priority: 10\n content: |\n - Use TypeScript strict mode\n - Prefer functional components\n - Use meaningful variable names\n\n - name: \"Testing\"\n priority: 5\n content: |\n - Write unit tests for all functions\n - Use describe/it pattern\n - Aim for 80% code coverage\n\noutputs:\n - file: \"CLAUDE.md\"\n template: \"claude\"\n - file: \".cursorrules\"\n template: \"cursor\"\n - file: \".windsurfrules\" \n template: \"windsurf\"\n```\n\n2. **Generate configuration files**:\n\n```bash\nai-rulez generate\n```\n\nThis creates `CLAUDE.md`, `.cursorrules`, and `.windsurfrules` with your rules properly formatted for each AI assistant.\n\n## \ud83d\udee0\ufe0f Commands\n\n```bash\n# Generate all configuration files\nai-rulez generate\n\n# Validate configuration\nai-rulez validate\n\n# Generate recursively in subdirectories\nai-rulez generate --recursive\n\n# Preview output without writing files\nai-rulez generate --dry-run\n\n# Show help\nai-rulez --help\n```\n\n## \ud83d\udd04 Git Integration\n\n### Pre-commit Hook\n\nAdd to your `.pre-commit-config.yaml`:\n\n```yaml\nrepos:\n - repo: https://github.com/Goldziher/ai-rulez\n rev: v1.0.0\n hooks:\n - id: ai-rulez-generate\n```\n\n### Lefthook\n\nAdd to your `lefthook.yml`:\n\n```yaml\npre-commit:\n commands:\n ai-rulez:\n run: ai-rulez generate\n files: git diff --cached --name-only\n glob: \"*.{ai-rulez,ai_rulez}.{yml,yaml}\"\n```\n\n## \ud83d\udcda Configuration\n\nThe tool looks for configuration files in this order:\n- `.ai-rulez.yaml`\n- `ai-rulez.yaml` \n- `.ai_rulez.yaml`\n- `ai_rulez.yaml`\n\n### User Rules vs. Coding Rules\n\nWhen creating AI rules, distinguish between two types of instructions:\n\n- **Coding Rules**: Technical guidelines about code quality, architecture, testing, etc.\n - Examples: \"Use TypeScript strict mode\", \"Write unit tests\", \"Follow REST conventions\"\n - Should be in the main configuration file committed to version control\n\n- **User Rules**: Personal preferences about communication style and interaction\n - Examples: \"Be concise in responses\", \"Use casual tone\", \"Address me as 'Chief'\", \"Always explain your reasoning\"\n - Perfect for `.local.yaml` files (e.g., `ai-rulez.local.yaml`) as they're personal and shouldn't affect the whole team\n - Allow individual developers to customize AI behavior without impacting others\n\n**Example local config** (`ai-rulez.local.yaml`):\n```yaml\nrules:\n - name: \"Communication Style\"\n content: \"Be concise and direct. Address me as 'Boss'. Always ask for clarification before making assumptions.\"\n - name: \"Response Format\"\n content: \"Provide code examples for every suggestion. Use bullet points for lists.\"\n```\n\n### Configuration Schema\n\n```yaml\nmetadata:\n name: string # Required: Project name\n version: string # Required: Version\n description: string # Optional: Description\n\nrules:\n - name: string # Required: Rule name\n priority: number # Required: Priority (1-10)\n content: string # Required: Rule content\n\nsections: # Optional: Organize rules into sections\n - title: string # Required: Section title\n priority: number # Required: Section priority\n content: string # Required: Section content\n\noutputs: # Required: At least one output\n - file: string # Required: Output filename\n template: string # Required: Template name or path\n\nincludes: # Optional: Include other config files\n - path/to/other.yaml\n```\n\n## \ud83c\udfa8 Templates\n\nBuilt-in templates:\n- `claude` - CLAUDE.md format\n- `cursor` - .cursorrules format \n- `windsurf` - .windsurfrules format\n- `default` - Generic format\n\nCustom templates use Go template syntax with access to `.Rules`, `.Sections`, `.Metadata`, etc.\n\n## \ud83d\udd27 Advanced Usage\n\n### Environment Variables\n\n- `AI_RULEZ_CONFIG` - Override config file path\n- `AI_RULEZ_DEBUG` - Enable debug output\n\n### Python API\n\n```python\nfrom ai_rulez.cli import main\nimport sys\n\n# Run ai-rulez programmatically\nsys.argv = ['ai-rulez', 'generate', '--dry-run']\nmain()\n```\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! Please see our [Contributing Guide](https://github.com/Goldziher/ai-rulez/blob/main/CONTRIBUTING.md).\n\n## \ud83d\udcc4 License\n\nMIT License - see [LICENSE](https://github.com/Goldziher/ai-rulez/blob/main/LICENSE)\n\n## \ud83d\udd17 Links\n\n- [GitHub Repository](https://github.com/Goldziher/ai-rulez)\n- [Documentation](https://github.com/Goldziher/ai-rulez#readme)\n- [Issues](https://github.com/Goldziher/ai-rulez/issues)\n- [Releases](https://github.com/Goldziher/ai-rulez/releases)\n- [npm Package](https://www.npmjs.com/package/ai-rulez)\n\n---\n\n**Note**: This Python package is a wrapper around the Go binary. The actual tool is written in Go for maximum performance and cross-platform compatibility.\n",
"bugtrack_url": null,
"license": null,
"summary": "\u26a1 Lightning-fast CLI tool (written in Go) for managing AI assistant rules - generate configuration files for Claude, Cursor, Windsurf and more",
"version": "1.1.4",
"project_urls": {
"Bug Reports": "https://github.com/Goldziher/ai-rulez/issues",
"Changelog": "https://github.com/Goldziher/ai-rulez/releases",
"Documentation": "https://github.com/Goldziher/ai-rulez#readme",
"Homepage": "https://github.com/Goldziher/ai-rulez",
"Source": "https://github.com/Goldziher/ai-rulez"
},
"split_keywords": [
"ai",
" ai-assistant",
" ai-rules",
" claude",
" cursor",
" windsurf",
" codeium",
" copilot",
" cli",
" cli-tool",
" configuration",
" config",
" rules",
" generator",
" golang",
" fast",
" development",
" developer-tools",
" automation",
" workflow",
" productivity",
" pre-commit",
" git-hooks",
" lefthook",
" code-generation",
" ai-development",
" assistant-configuration"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9389ac55166bbfd0e73348a587ce3b893a825da7e882728085b23da2d0e0cd81",
"md5": "c9268a1b271ac608a5894110f95da283",
"sha256": "4efd5737cee5979d362df1bfd373ef20876a4886921f0a5f4cdedef22d5234f2"
},
"downloads": -1,
"filename": "ai_rulez-1.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c9268a1b271ac608a5894110f95da283",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 8882,
"upload_time": "2025-07-09T06:38:28",
"upload_time_iso_8601": "2025-07-09T06:38:28.531875Z",
"url": "https://files.pythonhosted.org/packages/93/89/ac55166bbfd0e73348a587ce3b893a825da7e882728085b23da2d0e0cd81/ai_rulez-1.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "79f9c23ee69e245cbde2171f01fcd9b496f90b89afea1580998a4b4135ad6edf",
"md5": "265f7166e1918dfa94582d1ff8851f75",
"sha256": "e66290b055f401bef1a721185c2503d0c2b4dfd48a610565959858566560c3fb"
},
"downloads": -1,
"filename": "ai_rulez-1.1.4.tar.gz",
"has_sig": false,
"md5_digest": "265f7166e1918dfa94582d1ff8851f75",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 11435,
"upload_time": "2025-07-09T06:38:29",
"upload_time_iso_8601": "2025-07-09T06:38:29.733646Z",
"url": "https://files.pythonhosted.org/packages/79/f9/c23ee69e245cbde2171f01fcd9b496f90b89afea1580998a4b4135ad6edf/ai_rulez-1.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-09 06:38:29",
"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
