Ctxlint

ctxlint

One click adds this to your local Yaw MCP config so it's available in every Yaw Terminal session. Or install manually below.

Lint your AI agent context files, MCP server configs, and session data against your actual codebase. Context linting + MCP config linting + session auditing. 16 AI tools, 8 MCP clients, cross-project consistency, auto-fix. Works as a CLI, CI step, pre-commit hook, or MCP server.

Your CLAUDE.md is lying to your agent. Your .mcp.json has a hardcoded API key. ctxlint catches both.

Why ctxlint?

Every AI coding tool ships a context file: CLAUDE.md, .cursorrules, AGENTS.md, .mcp.json. These files are the single most important interface between you and your agent — they tell it what to build, how to test, where things live.

But context files rot fast. You rename a file, change a build script, or switch from Jest to Vitest — and your CLAUDE.md still says the old thing. Your agent follows those stale instructions faithfully, then fails. You lose 10 minutes debugging what turns out to be a wrong path in line 12 of a markdown file.

Multiply that across a team with 5 context files, 3 MCP configs, and 2 people who touched the build system last week — and you have a real problem with no existing solution.

ctxlint is a linter purpose-built for this. It reads your context files, cross-references them against your actual codebase, and catches the drift before your agent does.

• Instant startup — ships as a single self-contained bundle with zero runtime dependencies. npx downloads a ~400 KB tarball and starts immediately
• Catches real problems — broken paths, wrong commands, stale references, contradictions across files
• Smart suggestions — detects git renames and fuzzy-matches to suggest the right path
• Auto-fix — --fix rewrites broken paths automatically using git history
• Token-aware — shows how much context window your files consume and flags redundant content
• Every AI tool — supports Claude Code, Cursor, Copilot, Windsurf, Gemini, Cline, Aider, and 9 more
• Multiple outputs — text, JSON, and SARIF (GitHub Code Scanning)
• MCP server — 7 tools for IDE/agent integration with tool annotations for auto-approval
• Watch mode — --watch re-lints automatically when context files change

Install

Run directly (no install needed):

npx -y @yawlabs/ctxlint@latest

Project install (recommended for teams)

npm install -D @yawlabs/ctxlint
# or
pnpm add -D @yawlabs/ctxlint

Then add to your package.json scripts:

{
  "scripts": {
    "lint:ctx": "ctxlint --strict"
  }
}

Global install

npm install -g @yawlabs/ctxlint

Useful if you want ctxlint available in every project without per-project setup.

What It Checks

Supported Context Files

MCP Server Config Linting

ctxlint also lints MCP server configuration files — the JSON configs that tell AI clients which tools to connect to. These are context interfaces too: they shape what your agent can do.

# Lint context files + MCP configs
npx @yawlabs/ctxlint@latest --mcp

# Lint only MCP configs
npx @yawlabs/ctxlint@latest --mcp-only

# Include global/user-level configs (Claude Desktop, Cursor, Windsurf, etc.)
npx @yawlabs/ctxlint@latest --mcp-global

What MCP config files are scanned

With --mcp-global, also scans Claude Desktop, Cursor, Windsurf, and Amazon Q global configs.

What MCP config checks catch

Example MCP config output

MCP Configs
  .mcp.json
    ✗ mcp-security    Server "api": hardcoded Bearer token in a git-tracked file
    ✗ mcp-deprecated  Server "old-svc": SSE transport is deprecated — use "http"
    ✓ mcp-schema
    ✓ mcp-commands
  .cursor/mcp.json
    ✗ mcp-env  Server "api": Cursor uses ${env:VAR}, not ${VAR}
    ✓ mcp-schema
  .vscode/mcp.json
    ✗ mcp-schema  .vscode/mcp.json must use "servers" as root key, not "mcpServers"

Cross-file
    ⚠ Server "api" is configured differently in .mcp.json and .cursor/mcp.json
    ℹ Server "db" is in .mcp.json but missing from .cursor/mcp.json

Summary: 3 errors, 2 warnings, 1 info

MCP Config Linting Specification

The full specification for MCP config linting rules, the cross-client config landscape, and a machine-readable rule catalog are published as open specifications:

• MCP_CONFIG_LINT_SPEC.md — the full lint-rule set (rule count in the Specifications family table), the complete client/format reference, and implementation guidance. Tool-agnostic — any linter can implement it.
• mcp-config-lint-rules.json — Machine-readable rule catalog for programmatic consumption by AI agents, CI systems, and other tools.

Session Linting

ctxlint can audit AI agent session data — history files and memory entries — for cross-project consistency. Session checks compare your current project against sibling repos to catch drift and missing setup.

# Lint context files + session data
npx @yawlabs/ctxlint@latest --session

# Lint only session data
npx @yawlabs/ctxlint@latest --session-only

Session checks are opt-in because they access files outside the project directory (agent history in your home directory, sibling repos in the parent directory).

What session files are scanned

Checks whose signal is what the agent did (commands run, files written or read) also read the current project's Claude Code session transcripts, ~/.claude/projects/<encoded-project>/*.jsonl, bounded to the 5 most recent.

What session checks catch

Session Linting Specification

• AGENT_SESSION_LINT_SPEC.md — the full lint-rule set (rule count in the Specifications family table), the agent session data landscape across 8 agents, sibling detection strategy, and implementation guidance.
• agent-session-lint-rules.json — Machine-readable rule catalog.

Example Output

ctxlint v0.28.0

Scanning /Users/you/my-app...

Found 2 context files (1,847 tokens total)
  CLAUDE.md (1,203 tokens, 42 lines)
  AGENTS.md -> CLAUDE.md (symlink)

CLAUDE.md
  ✗ Line 12: src/auth/middleware.ts does not exist
    → Did you mean src/middleware/auth.ts? (renamed 14 days ago)
  ✗ Line 8: "pnpm test" — script "test" not found in package.json
  ⚠ Last updated 47 days ago. src/routes/ has 8 commits since.
  ⚠ testing framework conflict: "Vitest" in CLAUDE.md vs "Jest" in AGENTS.md
  ℹ Line 3: "Express" is in package.json dependencies — agent can infer this

Summary: 2 errors, 2 warnings, 1 info
  Token usage: 1,203 tokens per agent session
  Estimated waste: ~55 tokens (redundant content)

Options

Usage: ctxlint [options] [command] [path]

Arguments:
  path                 Project directory to scan (default: ".")

Options:
  --strict                  Exit code 1 on any warning or error (for CI)
  --checks <list>           Comma-separated checks to run (see below)
  --ignore <list>           Comma-separated checks to skip
  --fix                     Auto-fix broken paths using git history and fuzzy matching
  --fix-dry-run             Preview --fix changes without writing
  --yes                     Skip interactive confirmation prompts (required for --fix in TTY)
  --follow-symlinks         Allow --fix to write through symlinks (default: skip)
  --format <fmt>            Output format: text, json, or sarif (default: text)
  --tokens                  Show token breakdown per file
  --verbose                 Show passing checks too
  --quiet                   Suppress all output except errors (exit code only)
  --config <path>           Path to config file (default: .ctxlintrc in project root)
  --depth <n>               Max subdirectory depth to scan (default: 2)
  --mcp                     Enable MCP config linting alongside context file checks
  --mcp-only                Run only MCP config checks, skip context file checks
  --mcp-global              Also scan user/global MCP config files (implies --mcp)
  --session                 Enable session audit checks (cross-project consistency)
  --session-only            Run only session checks, skip context and MCP checks
  --skills                  Run agent-skill checks (~/.claude/skills + ~/.claude/agents)
  --skills-only             Run only agent-skill checks, skip everything else
  --hooks-global            Also scan the user-global ~/.claude/settings.json in the
                            dead-hook check (default scans project .claude/ only)
  --mcp-server              Start the MCP server (alias: `serve` subcommand)
  --lsp                     Start in LSP server mode (JSON-RPC over stdio for editor integration)
  --no-ignore-file          Disable .ctxlintignore suppression (see all findings)
  --watch                   Re-lint on context file changes
  -V, --version             Output the version number
  -h, --help                Display help

Commands:
  init                 Set up a git pre-commit hook
  serve                Start the MCP server (same as --mcp-server)

Available checks: paths, commands, staleness, tokens, tier-tokens, redundancy, contradictions, frontmatter, ci-coverage, ci-secrets, content-secrets, hook-coverage, mcp-schema, mcp-security, mcp-commands, mcp-deprecated, mcp-env, mcp-urls, mcp-consistency, mcp-redundancy, session-missing-secret, session-diverged-file, session-missing-workflow, session-stale-memory, session-duplicate-memory, session-loop-detection, session-memory-index-overflow, session-shared-temp-path, session-unverified-gate-claimed-clean, session-default-branch-accumulation, session-unresolvable-sha, session-large-read, skill-frontmatter, skill-broken-ref, skill-trigger-collision, skill-orphaned, skill-dead-tool-restriction

Passing any mcp-* check name implies --mcp. Passing any session-* check name implies --session. Passing any skill-* check name implies --skills.

Watch Mode

npx @yawlabs/ctxlint@latest --watch

Re-lints automatically when any context file, MCP config, or package.json changes. Useful during development when you're editing context files alongside code.

Use in CI

- name: Lint context files
  run: npx @yawlabs/ctxlint@latest --strict

Exit Codes

In non-strict mode ctxlint always exits 0 — it's a reporting tool by default. Pass --strict to enforce in CI.

GitHub Action

- name: Lint context files
  uses: yawlabs/ctxlint-action@v1

Or with options:

- name: Lint context files
  uses: yawlabs/ctxlint-action@v1
  with:
    args: '--strict --mcp'

SARIF Output (GitHub Code Scanning)

- name: Lint context files
  run: npx @yawlabs/ctxlint@latest --format sarif > ctxlint.sarif

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: ctxlint.sarif

Auto-fix

npx @yawlabs/ctxlint@latest --fix

When a broken path was renamed in git or has a close match in the project, --fix rewrites the context file automatically.

Pre-commit Hook

Built-in

npx @yawlabs/ctxlint@latest init

Sets up a git pre-commit hook that runs ctxlint --strict before each commit.

pre-commit framework

Add to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/yawlabs/ctxlint
    rev: v0.28.0
    hooks:
      - id: ctxlint

Config File

Create a .ctxlintrc or .ctxlintrc.json in your project root:

{
  "checks": ["paths", "commands", "tokens", "contradictions", "frontmatter"],
  "ignore": ["redundancy"],
  "ignoreRules": [
    { "check": "paths", "match": "^docs/archive/", "reason": "archived docs cite removed files" }
  ],
  "strict": true,
  "tokenThresholds": {
    "info": 500,
    "warning": 2000,
    "error": 5000,
    "aggregate": 4000,
    "tierBreakdown": 1000,
    "tierAggregate": 4000
  },
  "contextFiles": ["CONVENTIONS.md", "docs/ai-rules.md"],
  "exclude": ["fixtures/**", "examples/**"]
}

The contextFiles array adds custom file patterns to scan alongside the built-in list. Useful for project-specific context files like CONVENTIONS.md.

The exclude array is its counterpart: globs of context files to drop from the scan entirely. Use it for files that are not this project's agent context at all — test fixtures, example projects, vendored templates.

exclude removes files, where ignore / ignoreRules / .ctxlintignore suppress findings. That distinction matters for the cross-file checks: contradictions and redundancy/duplicate-content compare the discovered set and report against the literal (project) path, which no per-file glob can match. Excluding the files is the only way to silence a conflict between two files you never wanted linted. Reach for .ctxlintignore when a real context file has one noisy finding; reach for exclude when the file shouldn't be in the corpus.

Config Reference

Config file resolution order: .ctxlintrc → .ctxlintrc.json in the project root. Use --config <path> to point elsewhere. CLI flags override config fields.

CLI flags override config file settings. Use --config <path> to load a config from a custom location.

Ignore file (.ctxlintignore)

A .ctxlintignore file in the project root suppresses findings without touching .ctxlintrc. Each line is one rule, checkName [fileGlob] [# reason]:

# Blank lines and lines starting with # are skipped.
paths                    # every paths finding, in every file
tokens CLAUDE.md         # tokens findings in CLAUDE.md only
redundancy .claude/**    # redundancy findings in files under .claude/

• checkName is a name from the Available checks list under Options (paths, tokens, mcp-security, ...), not a rule ID. A name that is not a check is not rejected: the rule never matches, so it is reported as never fired.
• fileGlob is optional. Without one, the rule covers every file. With one, it covers only findings in files whose path matches — the project-relative path ctxlint prints, with forward slashes on every platform, and dotfiles included. Cross-file findings from contradictions and redundancy/duplicate-content are reported against the path (project); match them with that literal (contradictions (project)).
• # reason needs a space before the #. In paths#legacy, the whole token is read as the check name. Only the first two tokens are read, so there is no message regex here; use ignoreRules for that.
• Rules with a glob are applied first, in file order, then rules without one together with ignoreRules. A finding is dropped by the first rule that matches it.
• Dropped counts, rules that dropped nothing, and rules without a reason are listed in the same "Ignore rules" report as ignoreRules.
• --no-ignore-file skips the file for a run; ignoreRules still apply. --watch re-lints when the file changes.

Use as MCP Server

ctxlint ships with an MCP server that exposes seven tools (ctxlint_audit, ctxlint_mcp_audit, ctxlint_session_audit, ctxlint_skill_audit, ctxlint_validate_path, ctxlint_token_report, ctxlint_fix). All read-only tools declare annotations so MCP clients can skip confirmation dialogs.

Launch it with the serve subcommand (or the equivalent --mcp-server flag, kept for back-compat):

npx -y @yawlabs/ctxlint@latest serve

With Claude Code

claude mcp add ctxlint -- npx -y @yawlabs/ctxlint@latest serve

With .mcp.json (Claude Code project config, Cursor, Windsurf)

Create .mcp.json in your project root:

macOS / Linux / WSL:

{
  "mcpServers": {
    "ctxlint": {
      "command": "npx",
      "args": ["-y", "@yawlabs/ctxlint@latest", "serve"]
    }
  }
}

Windows:

{
  "mcpServers": {
    "ctxlint": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@yawlabs/ctxlint@latest", "serve"]
    }
  }
}

Tip: This file is safe to commit — it contains no secrets.

With VS Code / GitHub Copilot

Add to .vscode/mcp.json:

{
  "servers": {
    "ctxlint": {
      "command": "npx",
      "args": ["-y", "@yawlabs/ctxlint@latest", "serve"]
    }
  }
}

With Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "ctxlint": {
      "command": "npx",
      "args": ["-y", "@yawlabs/ctxlint@latest", "serve"]
    }
  }
}

JSON Output

npx @yawlabs/ctxlint@latest --format json

Returns structured JSON with all file results, issues, and summary — useful for building integrations or dashboards.

Specifications

ctxlint is the reference implementation of four open specifications for linting AI agent interfaces. These specs are tool-agnostic — any linter, IDE extension, or CI system can implement them.

All specs include machine-readable rule catalogs for programmatic consumption:

• context-lint-rules.json — context file rules and 16 supported format definitions
• mcp-config-lint-rules.json — MCP config rules and 8 client definitions
• agent-session-lint-rules.json — session lint rules and 8 agent data source definitions
• agent-skill-lint-rules.json — agent-skill lint rules (~/.claude/skills, ~/.claude/agents)

Also By Yaw Labs

• Yaw — The AI-native terminal

License

MIT