repo-rules

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