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