Jonparkdev Nix Config Ruler

Ruler

Ruler provides a single source of truth for AI agent instructions. Write rules once in Markdown, and ruler distributes them to every configured agent's native config format.

Repo: intellectronica/ruler

Quick Reference

For full CLI flags, see reference/cli.md.

Core Concepts

How It Works

1. You write rules as .md files in .ruler/ (local) or ~/.config/ruler/ (global)
2. ruler.toml maps agent names to output paths
3. ruler apply concatenates all rule files (sorted alphabetically) and writes them to each agent's config file
4. Each rule gets a source marker: <!-- Source: ruler/filename.md -->

Global vs Local Rules

Search order: local .ruler/ first (walks up directory tree), falls back to global config. Use --local-only to skip global fallback.

Supported Agents (30+)

Claude, Codex, Gemini CLI, Copilot, Cursor, Windsurf, Cline, Aider, Roo, JetBrains AI, Zed, Warp, and many more. Run ruler apply --help to see the full list.

Workflows

Add a New Rule

1. Create a focused .md file — one concern per file:

   # Testing Guidelines
   
   - Run the full test suite before committing: `npm test`
   - Write tests for all new functions. Prefer integration tests over unit tests.
   - Use descriptive test names that explain the expected behavior.
   

2. Place it in the rules directory (global or local)
3. Apply: ruler apply

Add a New Agent Target

Add to ruler.toml:

[agents.cursor]
enabled = true
output_path = ".cursor/rules/global.md"

Then ruler apply.

Set Up a New Project (Imperative)

cd /path/to/project
ruler init           # Creates .ruler/ruler.toml and starter files
# Edit .ruler/ rule files
ruler apply          # Fan out to agents
# Commit .ruler/ to the project repo

Troubleshoot

• Rules not appearing: Check ruler apply --dry-run output and verify file paths in ruler.toml
• Wrong agent getting rules: Check ruler.toml — ensure enabled = true and output_path is correct
• Undo changes: ruler revert restores from .bak files (only works if --no-backup wasn't used)

Rule Writing Best Practices

• One concern per file: commits.md, testing.md, security.md — not one giant file
• Actionable over aspirational: "Use rg for search" not "search efficiently"
• Use clear headings: Agents parse markdown structure for navigation
• Keep files short: Each rule file should be scannable in seconds
• Name files descriptively: They sort alphabetically — prefix with numbers if order matters (01-general.md)
• Avoid duplication: Global rules apply everywhere; project rules add project-specific context only

Declarative Nix Integration (This Config)

This nix-config manages ruler declaratively via a custom home-manager module. Rules are git-tracked source files that flow through nix to all agents on every rebuild.

Architecture

ai/ruler/rules/*.md          (source of truth, git-tracked)
        |
home/features/ai.nix         (declares rules + agents)
        |
modules/home/ruler.nix       (home-manager module)
        |
darwin-rebuild switch         (triggers activation)
        |
   ruler apply                (runs automatically)
        |
~/.claude/CLAUDE.md           (output)
~/.codex/AGENTS.md            (output)
~/.gemini/GEMINI.md           (output)

Current Configuration

Rules (in ai/ruler/rules/):

Agents (in home/features/ai.nix):

Modify Rules (Global Workflow)

1. Edit the rule file in ai/ruler/rules/ (or create a new one)
2. Register new rules in home/features/ai.nix under programs.ruler.rules:

   rules = {
     general = ../../ai/ruler/rules/AGENTS.md;
     my-new-rule = ../../ai/ruler/rules/my-new-rule.md;
   };
   

3. Commit: git add ai/ruler/rules/ home/features/ai.nix
4. Rebuild:

   sudo darwin-rebuild switch --flake ~/nix-config#$(scutil --get LocalHostName)
   

   Home-manager activation automatically runs ruler apply.

Add a New Agent

Edit programs.ruler.agents in home/features/ai.nix:

agents = {
  claude = { enable = true; outputPath = ".claude/CLAUDE.md"; };
  codex  = { enable = true; outputPath = ".codex/AGENTS.md"; };
  gemini = { enable = true; outputPath = ".gemini/GEMINI.md"; };
  cursor = { enable = true; outputPath = ".cursor/rules/global.md"; };
};

Then rebuild.

Key Files

For detailed nix module internals, see reference/nix-integration.md.

Reference

• reference/cli.md — Full CLI commands and flags
• reference/nix-integration.md — Nix module implementation details

Source: jonparkdev/nix-config — distributed by TomeVault.