ctxlint-action

Catches stale file references, dead commands, directory trees, and token waste in CLAUDE.md / AGENTS.md files before they reach main. Stale references cause AI agents to burn tool calls searching for files that no longer exist — ctxlint finds them in CI so they never land.

Quick start

name: Lint context files
on: [push, pull_request]
jobs:
  ctxlint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ctxlint/ctxlint-action@v1

Full example with inputs

- uses: ctxlint/ctxlint-action@v1
  with:
    path: .
    strict: true

Inputs

Input	Description	Default
path	Directory to scan	.
strict	Fail on warnings too	false
fail-on-warnings	Alias for strict	false

Outputs

Output	Description
issues-found	Number of issues detected
exit-code	Raw exit code from ctxlint

What ctxlint checks

• stale-file-ref — file paths mentioned in context files that no longer exist in the repo
• stale-command — shell commands referenced in context files that are not available or have changed
• no-directory-tree — hardcoded directory tree dumps that go stale as the codebase evolves
• inferable-stack — tech stack details that can be inferred from package.json, go.mod, etc.
• token-waste — redundant, padded, or low-signal content burning context window tokens
• mcp-config — invalid or misconfigured MCP server entries in .mcp.json / .cursor/mcp.json

Related

• @ctxlint/ctxlint — the underlying npm package
• github.com/ctxlint/Ctxlint — source repository