Find stale local paths and command entry points in CLAUDE.md, AGENTS.md, and HANDOFF.md, without executing anything in them. Optionally compare declared evidence file hashes.
This is an offline, read-only CLI. A matched entry means the file or npm script key exists. It does not mean a command ran, a test passed, or an instruction is correct. Version 0.1.0 is a source release; it has not been published to a package registry.
Python 3.11+ and a POSIX system supporting directory-relative no-follow opens are required. Local verification was performed on macOS with Python 3.14.7. The source-release CI also runs the test suite on Ubuntu and macOS with Python 3.11 and 3.14; see the workflow. Windows has no supported safe-open implementation.
git clone https://github.com/widechaos/context-refcheck.git
cd context-refcheck
python3 -m venv .venv
.venv/bin/python -m pip install .
.venv/bin/context-refcheck --versionInstallation may download the setuptools build tool. Runtime uses only the Python standard library, needs no API keys, and makes no network requests. The source package installs the context-refcheck executable.
Each healthy project has just one instruction file and no configuration. Each broken counterpart contains old references. The scripts in these examples deliberately throw if executed; Context Refcheck only checks their entry points.
.venv/bin/context-refcheck check --root examples/python/healthy
.venv/bin/context-refcheck check --root examples/python/broken
.venv/bin/context-refcheck check --root examples/javascript/healthy
.venv/bin/context-refcheck check --root examples/javascript/broken
.venv/bin/context-refcheck check --root examples/nested/healthy --doc nested/HANDOFF.md
.venv/bin/context-refcheck check --root examples/nested/broken --doc nested/HANDOFF.mdThe healthy commands exit 0. Broken Python and JavaScript projects report ENTRY_MISSING; the nested example also reports PATH_MISSING. Broken commands exit 1. These examples are invented; they are not production adoption evidence.
For machine-readable output:
.venv/bin/context-refcheck check --root examples/javascript/broken --format jsonEvery report includes execution=never, a coverage description, matched/skipped counts and whether input processing completed. Missing default files are informational. If none of the selected documents can be read, the command exits 2. --doc replaces the default document set; repeat it to select more files. There is no recursive discovery or search of parent directories.
To repair an example, copy its broken directory to a temporary location you control, change the old reference to the corresponding healthy reference, and recheck it. The CLI does not edit files or accept new hashes for you.
- Inline local links, including
[guide](docs/guide.md)and[guide](<docs/my guide.md>), and path-like inline code such as./scripts/check.py. - Whole inline commands and single-line
sh,bash,shellorconsolefenced blocks: exactlypython3 relative/file.pyornpm run name. A single$prompt is accepted in a shell fence. Python checks existence of a regular.pyfile; npm checks a nonempty string key in the instruction document's siblingpackage.json. - Optional
.context-refcheck.jsondeclarations bind a check to exact document text, and can compare SHA-256 of explicitly declared evidence. See the format.
Paths are relative to the instruction file. A nested handoff may use ../scripts/check.py if lexical normalization stays under the explicit root. Symlinks are rejected even if they point inside the root. Sensitive paths and special files are blocked. See the safety boundary.
Multi-line fences and other language code examples are skipped as a whole, so fictitious files in examples do not become missing-path findings. This also means real commands inside a multi-line shell block are not checked. Unsupported single-line shell commands and recognized inline command candidates produce warnings; they are never interpreted as path fragments.
This parser handles a small Markdown subset. Full/reference-style links, nested parentheses, multi-backtick inline spans, HTML links and arbitrary shell syntax are unsupported. Recognized unsupported forms warn; bare prose paths, indented code, shortcut references and unrecognized command names may be outside detection. Relative inline code is path-like only when it contains / or \, or starts with ~. Use a link for a bare filename. URL targets and fragments are skipped without network access. A file matching its hash only establishes byte equality with the declaration; there is no Git version, test result, factual or semantic validation.
Exit codes: 0 complete, no errors/warnings; 1 findings or recognized unsupported forms; 2 input/platform/limit/read failures made the check incomplete. Informational default absence and deliberate example/URL skips do not cause a warning. complete refers to processing selected input within this documented coverage, never comprehensive validation.
.venv/bin/python -m unittest discover -s tests -v
.venv/bin/python -m pip uninstall -y context-refcheckTests use synthetic temporary directories and shipped examples only. Release files and third-party notices define the intended public scope. MIT licensed; no dependency runtime is bundled.
Related tools: markdownlint for Markdown style, lychee for broad link checks, agent-handoff and context-handoff-bundle for handoff lifecycle and drift workflows. Their features were reviewed in author documentation, not benchmarked here. Context Refcheck focuses on existing instruction references and static command entries; hash drift checking is already present in other tools.
See the source-based scope comparison for overlap with the existing Context Doctor projects and the provisional naming check.