Ctxlint

Community

Lint your AI agent context files (CLAUDE.md, AGENTS.md, etc.) against your actual codebase.

★ 10 Stars Category · Dev Tools Popular Source revision 9b7214904195

57FMRS · C

Ctxlint provides comprehensive auditing of context files, MCP configs, sessions, and skills as an MCP server. The tool set is balanced, and read-only tools declare annotations for auto-approval to streamline workflows. It requires access to the target project files and is valuable for teams leveraging its CLI and MCP server capabilities. Not official but MIT-licensed and well documented.

Reliability

9/20

Security and permissions

11/20

Maintenance

9/20

Documentation

15/20

Setup experience

13/20

Read the FMRS scoring method →

Ctxlint is a linter purpose-built for AI tool context files. It reads files like CLAUDE.md, AGENTS.md, .cursorrules, .mcp.json and cross-references them against your actual codebase to catch stale paths, wrong commands, redundant content, contradictions across files, and more. It supports 16 AI tools and 8 MCP clients, and works as a CLI, CI step, pre-commit hook, or MCP server. The MCP server exposes 7 tools for auditing context files, MCP configs, session data, and skill definitions.

Tools

ctxlint_audit

Audit a project's context files (CLAUDE.md, AGENTS.md, etc.) for paths, commands, staleness, redundancy, and more.

ctxlint_mcp_audit

Audit MCP config files (.mcp.json, .cursor/mcp.json, etc.) for schema, security, commands, deprecated transports, etc.

ctxlint_session_audit

Audit AI agent session data (history, memory) for cross-project secrets, config drift, stale memory, and loop detection.

ctxlint_skill_audit

Audit Claude Code skill and agent definitions (~/.claude/skills, ~/.claude/agents) for frontmatter, broken refs, trigger collisions, etc.

ctxlint_validate_path

Validate whether a path exists in the project and suggest the correct path based on git history.

ctxlint_token_report

Report token consumption of context files and redundant content.

ctxlint_fix

Automatically fix broken paths in context files using git history.

Setup

### Run via npx (no install needed)

npx -y @yawlabs/ctxlint@latest serve

### Add to MCP clients
For clients that support a project-level MCP config (e.g., Claude Code, Cursor, Windsurf), create a .mcp.json in the project root:

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

For Claude Desktop, add the same config to claude_desktop_config.json.

For VS Code / GitHub Copilot, use the same server config in .vscode/mcp.json (but with "servers" as the root key).

claude_desktop_config.json

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

Generate and validate client config

Fit and risk

Best for

Developers and teams using AI coding assistants (e.g., Claude Code, Cursor).
Projects with multiple context files and complex structure.
Teams that need to maintain accurate agent context.
Environments with strict security requirements for MCP configs (e.g., no hardcoded API keys).

Not for

Projects that don't use AI context files.
Simple, solo projects where files change infrequently (may be overkill).
Non-critical projects that don't require strict context maintenance.

Required permissions

Reads context and config files in the project directory (e.g., CLAUDE.md, .mcp.json).
Optionally reads user-level config files (e.g., ~/.claude/settings.json) and global MCP configs (with --mcp-global).
Optionally reads agent history and memory files in the user's home directory (e.g., ~/.claude/history.jsonl) when session or skill audits are enabled.
Optionally writes context files to fix broken paths when --fix is enabled.

Risks and side effects

Auto-fix (--fix) may modify files unexpectedly; preview with --fix-dry-run and review changes.
Session audit accesses sensitive history files in the home directory; enable only in trusted environments.
The tool reads config and context files that may contain secrets (e.g., API keys); ensure access is controlled.
Redundancy checks may produce false positives as inferred content may vary by context.

Troubleshooting

Ensure your project contains context files to audit (e.g., CLAUDE.md). If none, the MCP server may report no files to audit.
If using session or skill audits, check that the appropriate flags (--session, --skills) are passed and that the corresponding files exist.
On Windows, add a `cmd /c` wrapper when using npx: `"command": "cmd", "args": ["/c", "npx", "-y", "@yawlabs/ctxlint@latest", "serve"]`.
If the server fails to start, confirm Node.js and npx are installed and the npm registry is reachable.
For path errors, see suggested paths in the output, or enable --fix to auto-correct (review changes in version control).

Use cases

Automatically audit context files before AI coding sessions to ensure agents follow the latest code structure.

Run as a CI step to prevent context files from drifting from the actual codebase.

Enforce consistent rules across multiple context files in a team to avoid conflicting instructions.

Integrate with IDEs or coding assistants via MCP server for real-time linting.

Supported clients

Claude DesktopFull support

Claude CodeFull support

CursorFull support

WindsurfFull support

VS CodeFull support

GitHub CopilotFull support

Related MCP servers

Compare with other MCP servers