Rules Agent

Extract and index AI coding instructions from rules files (CLAUDE.md, AGENTS.md, .cursorrules, etc.).

Why?

You’ve written the rules. There’s a CLAUDE.md at the root, an AGENTS.md for Codex, a .cursorrules file, and whatever else lives under .cursor/rules/ or .github/instructions/. But when you open an agent session and say “review this PR,” it doesn’t see all of them.

repo-rules-agent builds one queryable index from every rules file in your repo. A query scoped to the work in front of you — e.g. --task code-review --lang py --severity must — returns the ~15 rules that actually apply, not 8,000 tokens of rules files.

How it works

Four stages: discover → extract → index → query.

• Discover sweeps ~40 known rules-file conventions across four priority tiers — root files, tool-specific paths, rules directories with globs, and a recursive ** tier. It resolves @include-style directives, so a CLAUDE.md that’s just a pointer to AGENTS.md counts as one source, not two.
• Extract sends each file to an LLM via the OpenAI tool-calling protocol. The model fills a pydantic-validated schema — see Rule Model. Large files are chunked on Markdown headings via chonkie.
• Index merges near-duplicates by text similarity and flags potential conflicts — similar rules with contradictory severities — for human resolution.
• Query returns rules scoped to the current task. Filter by task, language, severity, scope; output as a table, JSON, or a prompt-ready block.

Dependencies

• uv — Python package manager
• git — used for blob SHA computation during indexing
• Ollama — required if you use the default local provider; not needed if you configure OpenAI, Anthropic, or another hosted provider

Setup

# Install dependencies
uv sync

Configuration

The tool works with any OpenAI-compatible API provider. By default, it connects to a local Ollama instance; OpenAI and Anthropic are also supported.

Copy .env.example to .env and uncomment the provider you want to use:

cp .env.example .env
# Edit .env with your API keys

The .env file is gitignored and loaded automatically at startup via python-dotenv. Shell environment variables take precedence over .env values, so you can always override a .env setting with an explicit export.

Providers

Local (Ollama — default, no API key needed):

ollama pull glm-4.7-flash:latest
uv run repo-rules-agent index /path/to/repo

Local models vary in tool-calling reliability; for the highest-quality extraction, use OpenAI or Anthropic.

Anthropic (add to .env):

RULES_AGENT_LLM__BASE_URL=https://api.anthropic.com/v1
RULES_AGENT_LLM__API_KEY_ENV=ANTHROPIC_API_KEY
RULES_AGENT_LLM__EXTRACTION_MODEL=claude-haiku-4-5
ANTHROPIC_API_KEY=sk-ant-...

OpenAI (add to .env):

RULES_AGENT_LLM__BASE_URL=https://api.openai.com/v1
RULES_AGENT_LLM__API_KEY_ENV=OPENAI_API_KEY
RULES_AGENT_LLM__EXTRACTION_MODEL=gpt-4o-mini
OPENAI_API_KEY=sk-proj-...

All LLM settings can also be changed in src/rules_agent/config.toml.

Usage

Discover rules files

Check which files would be processed without extracting:

uv run repo-rules-agent discover /path/to/repo

Index a repository

Extract rules from all discovered files. The index is written to a per-user cache directory by default (invisible to the repo), and query reads from the same place.

# Index the current repo (writes to the cache; prints the resolved path)
uv run repo-rules-agent index /path/to/repo

# Override the output path
uv run repo-rules-agent index /path/to/repo -o rules-index.json

Query rules

Filter and format rules from the cached index. With no positional argument, query reads the cached index for the current directory.

# Table format (default)
uv run repo-rules-agent query --task code-review

# JSON format
uv run repo-rules-agent query --task code-review --format json

# Prompt format (for injection into LLM prompts)
uv run repo-rules-agent query --task code-review --format prompt

# Filter by language
uv run repo-rules-agent query --task code-review --lang py

# Filter by severity
uv run repo-rules-agent query --severity must

# Query an explicit index file instead of the cache
uv run repo-rules-agent query rules-index.json --task code-review

Summarize the index

Print rule counts per file plus breakdowns by severity, task, and language. Use this for overview questions instead of piping query into a script.

# Summary for the cached index of the current directory
uv run repo-rules-agent stats

# Or pass an explicit index file
uv run repo-rules-agent stats rules-index.json

Inspect the cache

uv run repo-rules-agent cache path          # where the cwd's index lives
uv run repo-rules-agent cache list          # all cached indices, newest first
uv run repo-rules-agent cache clear --all   # wipe the cache

Evaluate extraction quality

Score how well the LLM extracted rules using a judge model:

# Evaluate from an existing index (requires --repo to read source files)
uv run repo-rules-agent eval rules-index.json --repo /path/to/repo

# Or run the full pipeline (discover → extract → eval) from a directory
uv run repo-rules-agent eval /path/to/repo

# Save results to file
uv run repo-rules-agent eval rules-index.json --repo /path/to/repo -o eval-results.json

# Use a different judge model
uv run repo-rules-agent eval /path/to/repo --judge-model gpt-4o-mini

The judge scores each file on precision (no hallucinated rules), recall (no missed rules), and F1.

Install as an agent skill

The bundled SKILL.md works with any agent that speaks the open skill format — Claude Code, OpenAI Codex CLI, and Cursor. Only the destination directory differs.

# Claude Code (default), repo-local
uv run repo-rules-agent install-skill

# Claude Code, user-wide
uv run repo-rules-agent install-skill --scope user

# Codex CLI (user-scope only — Codex doesn't support project-scope skills)
uv run repo-rules-agent install-skill --target codex --scope user

# Cursor, repo-local
uv run repo-rules-agent install-skill --target cursor

# All supported agents at once
uv run repo-rules-agent install-skill --target all --scope user

Discovery Tiers

Files are discovered in priority order:

Rule Model

Each extracted rule includes:

• title: Concise rule title with key technical context
• description: 2-3 sentence description (what, when, why)
• category: open string. Preferred values surface in the tool schema as examples — crash_or_hang, logic_error, performance, security, error_handling, readability, code_style, maintainability, testability, best_practice — but any lowercase_snake_case identifier is accepted, so models can return values like architecture or type_safety without the rule being dropped
• tasks: code-review, code-generation, code-questions
• languages: ts, py, go, etc. or “all”
• scope: repo, directory, file-pattern
• severity: must, should, can
• source_file: Origin file for tracing

Development

# Format code
make format

# Run tests
make test

# Format + test
make check

Support

Please open issues and feature requests here: https://github.com/unblocked/repo-rules-agent/issues

Copyright © NextChapter Software