repo-rules-agent

repo-rules-agent

Extract and query AI coding rules (CLAUDE.md, .cursorrules, .github/copilot-instructions.md, etc.) from the current repository.

Default workflow

When you need to consult the rules for a task, go straight to query (or stats for overview questions). Don't pre-check whether the index exists — the commands print a clear error with the exact remedy if it doesn't.

1. If a subsequent command reports "no index found at …", build the index (one-time per repo, or after a rules file changes):

   repo-rules-agent index .
   

   The index is written to a per-user cache directory (not the repo). The command prints the exact path.

2. Query the index scoped to the current task:

   repo-rules-agent query \
     --task <code-review|code-generation|code-questions> \
     [--lang py|ts|go|...] \
     [--severity must|should|can] \
     --format prompt
   

   Use --format prompt when injecting rules into your own context. Use --format table when showing them to the user.

Overview questions ("what rules does this repo have?", "how many rules per file?")

Use stats — it reads the cached index and prints rule counts per file plus breakdowns by severity, task, and language. Do NOT pipe query into a custom script for this.

repo-rules-agent stats

Commands

index — Extract rules and build a JSON index

repo-rules-agent index <repo-path> [-o output.json] [-v]

• Discovers rules files, extracts individual rules via any OpenAI-compatible LLM, and writes a JSON index.
• Default output location is a per-user cache directory keyed by the absolute repo path.
• -o path: override the output path.
• Defaults to local Ollama (glm-4.7-flash:latest); configure provider via RULES_AGENT_LLM__BASE_URL and RULES_AGENT_LLM__API_KEY_ENV.

stats — Summarize a rules index

repo-rules-agent stats [index.json] [-v]

Reads the cached index (or a path you give) and prints total rule count, rules per file, and breakdowns by severity, task, and language. Use this for overview questions instead of piping query output into a script.

query — Filter and retrieve rules from an index

repo-rules-agent query [index.json] [options]

With no positional argument, reads the cached index for the current directory.

Options:

• -t, --task: Filter by task type (code-review, code-generation, code-questions)
• -l, --lang: Filter by language (py, ts, go, java, rust, etc.)
• -s, --scope: Filter by scope (repo, directory, file-pattern)
• --severity: Filter by severity (must, should, can)
• -f, --format: Output format (table, json, prompt)

discover — Find rules files without extracting

repo-rules-agent discover <repo-path> [-v]

Lists all rules files found in a repository with their priority tiers and sizes.

cache — Manage the per-repo index cache

repo-rules-agent cache path [repo-path]   # print where this repo's index lives
repo-rules-agent cache list               # list every cached index, most recent first
repo-rules-agent cache clear <repo-path>  # remove one repo's cache
repo-rules-agent cache clear --all        # wipe the whole cache

eval — Evaluate extraction quality with LLM judge

repo-rules-agent eval <source> [--repo <path>] [-o results.json] [--judge-model <model>] [-v]

• <source>: index JSON path or a repository directory (directory runs the full pipeline).
• --judge-model: model used as judge (default: qwen3-coder:30b).
• Reports precision, recall, and F1 per file and overall.

install-skill — Install this skill

repo-rules-agent install-skill [--target claude|codex|cursor|all] [--scope project|user] [--force]

The same SKILL.md works across Claude Code, Codex CLI, and Cursor. Only the destination directory differs:

Target	Project scope	User scope
claude (default)	.claude/skills/repo-rules/SKILL.md	~/.claude/skills/repo-rules/SKILL.md
codex	n/a (use --scope user)	~/.codex/skills/repo-rules/SKILL.md
cursor	.cursor/skills/repo-rules/SKILL.md	~/.cursor/skills/repo-rules/SKILL.md
all	claude + cursor (codex skipped)	claude + codex + cursor

• --force: overwrite any existing SKILL.md without confirmation.