ai-rulez


Nameai-rulez JSON
Version 1.1.4 PyPI version JSON
download
home_pagehttps://github.com/Goldziher/ai-rulez
Summary⚡ Lightning-fast CLI tool (written in Go) for managing AI assistant rules - generate configuration files for Claude, Cursor, Windsurf and more
upload_time2025-07-09 06:38:29
maintainerNone
docs_urlNone
authorNa'aman Hirschfeld
requires_python>=3.8
licenseNone
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
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # 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"
}
        
Elapsed time: 0.42798s