AgentWhy

git check-ignore -v for AI coding-agent instructions.

Explain which instructions apply to one file, why they win, and where they quietly conflict — before you blame the model.

The ten-second demo

npx --yes github:RRXXZZYY/agentwhy demo --out agentwhy-demo.html

Open agentwhy-demo.html. It is a deterministic synthetic repository, so it does not read or upload your code.

To explain a real target:

npx --yes github:RRXXZZYY/agentwhy explain src/service.ts

The output answers three questions:

1. Which instruction files were discovered for this exact target?
2. Which files apply, in what order, and which files are shadowed?
3. Where could duplicates, contradictions, broken links, secrets, or context pressure surprise the agent?

Why this exists

Agent instructions now live at several levels of a repository. A root policy can combine with a nested policy, while an override can silently replace a sibling. Add editor-specific rule files and the effective prompt becomes hard to reason about.

AgentWhy turns that invisible stack into provenance you can inspect in a terminal, a standalone visual report, or CI. It is not another prompt template and it does not call an LLM.

Supported profiles

Profile	Sources inspected	Confidence
Codex	AGENTS.override.md, then AGENTS.md, root → target	Documented behavior
Claude	ancestor CLAUDE.md files	Best-effort inspection
Gemini	ancestor GEMINI.md files	Best-effort inspection
Copilot	.github/copilot-instructions.md	Best-effort inspection
Cursor	.cursorrules, simple .cursor/rules/*.mdc globs	Best-effort inspection

The Codex profile follows the public AGENTS.md discovery and precedence guide. Other profiles are intentionally labeled best-effort because vendor behavior can change and some formats have richer semantics than the 0.1 parser models.

Commands

agentwhy explain <target> [options]
agentwhy demo [--out agentwhy-demo.html]
agentwhy rules

--root <directory>       repository root (default: current directory)
--agent <name|all>       repeatable; default: codex
--format <type>          pretty, json, html, or sarif
--out <file>             write instead of printing
--budget-bytes <number>  warning threshold (default: 32768)
--strict                 exit 1 on errors or warnings

Examples:

# Compare every supported instruction source for a target
agentwhy explain packages/api/src/route.ts --agent all

# Generate a shareable report with no external scripts, fonts, or styles
agentwhy explain src/service.ts --format html --out agentwhy.html

# Feed relative-path diagnostics into code scanning
agentwhy explain src/service.ts --format sarif --out agentwhy.sarif --strict

Findings

Rule	What it catches	Default
AW001	likely positive/negative instruction conflict	warning
AW002	exact normalized duplicate across applied sources	note
AW003	missing or root-escaping local Markdown reference	warning
AW004	instruction chain above the configured byte budget	warning
AW005	secret-shaped value; the value is never printed	error
AW006	same-directory instruction file shadowed by an override	note
AW007	instruction candidate is empty and skipped	warning

AW001 is a transparent lexical heuristic, not semantic proof. It reports the two source lines and the shared-key-term score so a human can make the decision. See the rule reference for boundaries and examples.

Use it in GitHub Actions

name: Agent instruction check
on: [pull_request]

jobs:
  agentwhy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: RRXXZZYY/agentwhy@v0.1.0
        with:
          target: src/service.ts
          agent: all
          strict: true

Privacy and security

• Runs locally with zero runtime dependencies and no telemetry.
• Makes no network requests.
• Never prints absolute filesystem paths.
• Redacts secret-shaped values from JSON and HTML output.
• Refuses to resolve a target outside the selected root.
• Escapes repository-controlled text in the standalone HTML report.

AgentWhy still reads the instruction files it analyzes. Treat generated reports as repository artifacts and review them before sharing.

Design boundaries

AgentWhy explains static instruction provenance. It does not reproduce hidden system prompts, model-side policy, runtime memory, IDE state, or every vendor's full parser. Token counts are an explicit four-characters-per-token estimate, not model-specific tokenization. Budget warnings do not claim that an agent will truncate at exactly that boundary.

Read the architecture, project positioning, and roadmap for the rationale.

Development

npm ci
npm test
npm run test:coverage
npm run pack:check

Node.js 20 or newer is required. Contributions are welcome under the MIT license.