WhichRules

See exactly which instructions your AI coding agent receives.

One target file. Five agents. Every rule and conflict, explained locally.

Quick start · Why · Agents · Contributing

---

---

AI coding tools read different instruction files, use different scoping rules, and often load more than one file at once. A repository can quietly say “use pnpm” in AGENTS.md and “use npm” in CLAUDE.md—then leave the agent to guess.

whichrules calculates the effective instruction stack for a specific file and flags contradictions before an agent acts on them.

$ npx whichrules src/checkout.ts --agent all

whichrules  what your agent sees
target    src/checkout.ts
agents    codex, claude, cursor, copilot, gemini
result    4 files · 12 rules · 4 conflicts

Instruction stack
├─ AGENTS.md                         [codex, cursor, copilot] · 4 rules
├─ CLAUDE.md                         [claude, cursor] · 4 rules
├─ .github/copilot-instructions.md  [copilot] · 2 rules
└─ .cursor/rules/typescript.mdc      [cursor] · 2 rules

Conflicts
● Package manager [cursor]: pnpm ↔ npm
  AGENTS.md:3  Always use pnpm for dependency management.
  CLAUDE.md:3  Use npm for all package scripts.

Quick start

No install or configuration is required. Node.js 20+ is the only prerequisite.

npx whichrules src/api.ts --agent codex

Inspect all supported agents:

npx whichrules . --agent all

Create a self-contained report you can attach to an issue or PR:

npx whichrules src/api.ts --agent all --html report.html

Fail CI when conflicting instructions are detected:

npx whichrules . --agent all --check

Diagnose repository-wide instruction health and create a starter root file when it is missing:

npx whichrules doctor
npx whichrules doctor --fix

Use the same check in CI. It fails on conflicting rules; add --strict to fail on warnings such as missing root guidance:

npx whichrules ci --strict

Try the included deliberately-conflicted demo after cloning:

npm run demo
npm run report

Why WhichRules?

Instruction files now behave like a second configuration system for a repository, but they lack the observability developers expect from ordinary config:

• Hierarchy is invisible. A nested AGENTS.md can add to or override rules higher in the tree.
• Tools disagree. Codex, Claude Code, Cursor, Copilot, and Gemini discover different files.
• Globs are easy to miss. Cursor and Copilot rules may only apply to particular paths.
• Drift is silent. Duplicated rules gradually contradict one another.
• Reviews show files, not effective context. It is hard to see what changes for a particular source file.

WhichRules is deterministic, offline, zero-dependency, and safe to run on private repositories. It does not call a model or upload source code.

Supported agents

Agent	Instruction sources in v0.1
Codex	Hierarchical AGENTS.md
Claude Code	Hierarchical CLAUDE.md, .claude/rules/*.md
Cursor	AGENTS.md, CLAUDE.md, .cursor/rules/*.mdc, .cursorrules
GitHub Copilot	AGENTS.md, .github/copilot-instructions.md, .github/instructions/*.instructions.md
Gemini	Hierarchical GEMINI.md

Path-scoped rules support common globs, paths, applyTo, and alwaysApply frontmatter fields. More exact per-agent precedence modeling is tracked on the roadmap.

Commands

whichrules <command> [target] [options]

Commands:
  explain             show the effective instruction stack
  doctor              find missing, empty, and conflicting instructions
  ci                  run doctor as a CI gate

-a, --agent <name>  codex, claude, cursor, copilot, gemini, or all
--root <path>        repository root (auto-detected by default)
--json               print machine-readable JSON
--html [file]        write a shareable HTML report
--check              exit 1 when conflicts are found
--no-color           disable ANSI colors

The JSON output is versioned with a top-level version field so editor extensions and CI integrations can build on it.

What counts as a conflict?

v0.1 deliberately uses conservative, explainable checks. It detects explicit disagreement in common categories such as package manager, quote style, semicolon policy, test runner, and formatter. Every finding includes file and line evidence.

This is not an LLM judge. It will miss semantic contradictions, but it also never sends your repository to a third party or invents a conflict it cannot point to.

Roadmap

• Security checks for prompt injection, hidden Unicode, dangerous hooks, and MCP config
• whichrules diff for pull requests
• Exact precedence simulation for every supported agent
• VS Code extension with “effective rules” CodeLens
• SARIF output and GitHub annotations
• Rule deduplication and stale-reference detection
• Community-maintained adapters for additional agents

Have an agent or edge case we should support? Open an issue with a minimal example.

Philosophy

Agent instructions are code. They deserve scopes, diffs, tests, and debuggability.

Contributing

Small reproductions for new agents and scoping edge cases are especially valuable. See CONTRIBUTING.md.

Maintaining or launching the project? See the practical launch playbook and release checklist.

License

MIT © 2026 WhichRules contributors