Repo Context Doctor
Map the instruction files a coding agent can inherit, then find conflicts, stale references, duplicated rules, unsafe guidance, and context pressure before they change agent behavior.
Repo Context Doctor is a read-only repository linter and graph inspector. It does not generate rules, package a codebase, call an LLM, or upload source content. That boundary is intentional: Rulesync synchronizes agent configuration, Repomix packages repositories for model input, and DheerG/context-doctor provides interactive context diagnosis. This tool verifies the instruction surface itself.
The executable is named
repo-context-doctor(orrctx-doctor) to avoid colliding with the establishedcontext-doctorpackage, which profiles and optimizes LLM conversation windows.
Install
npm install --save-dev repo-context-doctor
npx repo-context-doctor check .
Node.js 20 or newer is required.
What it discovers
| Ecosystem | Sources | Activation evidence |
|---|---|---|
| OpenAI Codex | AGENTS.md, AGENTS.override.md |
repository and nested-directory scope |
| Claude Code | CLAUDE.md, CLAUDE.local.md |
project/local-style override layers |
| Cursor | .cursorrules, .cursor/rules/**/*.mdc |
rule files and Cursor rule scope |
| Gemini CLI | GEMINI.md |
project and ancestor files |
| GitHub Copilot | .github/copilot-instructions.md |
repository instruction file |
| Windsurf | .windsurfrules, .windsurf/rules/**/*.md |
rule files and rule scope |
Use --include-global to include ancestor files above the project root. Without it, scanning stays inside the selected repository.
Checks
CTX001contradictory package-manager, test, lint, or build guidanceCTX002references to missing filesCTX003missingnpm runscriptsCTX004duplicated directives loaded from multiple sourcesCTX005provider context approaching its configured budgetCTX008unsafe shell, secret-handling, or safety-bypass guidance
Every finding includes evidence paths and line numbers. JSON redacts directive bodies; SARIF points back to source files; Mermaid shows provider-to-source and override relationships.
Commands
# Human report; exits 1 for errors
npx repo-context-doctor check .
# Inspect a nested service and one provider
npx repo-context-doctor check . --cwd services/payments --agent codex
# Include ancestor instruction files explicitly
npx repo-context-doctor check . --include-global --json > context-report.json
# Pull-request annotations and graph visualization
npx repo-context-doctor check . --sarif > context.sarif
npx repo-context-doctor graph . --mermaid > context.mmd
# Treat warnings as blocking in a strict CI gate
npx repo-context-doctor check . --strict
Exit codes are 0 for a clean report, 1 for an actionable finding (or a warning under --strict), and 3 when the scanner cannot complete. The JSON schema is versioned and contains no instruction bodies.
Library API
import { scan } from "repo-context-doctor";
const report = await scan(process.cwd(), ".", undefined, { includeGlobal: true });
console.log(report.sources, report.findings, report.edges);
Privacy and limits
- Offline and read-only; no subprocesses, model calls, network access, or file writes.
- Source paths, line numbers, normalized metadata, and graph edges are retained; instruction bodies are omitted from JSON reports.
- Natural-language interpretation and undocumented provider precedence cannot be proven statically.
- Findings are evidence for review, not a guarantee of what a closed-source agent will do.
Development
npm install
npm run lint
npm test
npm run test:cli
npm pack --dry-run
Issues and pull requests are welcome in the GitHub repository.
License
MIT © Debaditya Hait