SuperAPI AI Directory
Partner with us中文AI newsFavorites
All toolsAI agentsctxlint

ctxlint

ctxlint is a code linter designed specifically for AI agent context files. It can read context files such as CLAUDE.md, .cursorrules, AGENTS.md, .mcp.json, and cross-check them against the actual codebase, uncovering issues such as broken paths, incorrect commands, outdated references, contradictions between files, and hardcoded secrets in MCP configurations. The tool runs as a command line, can be used via npx without installation, and also supports local project installation. It can be integrated into CI, Git hooks, or run as an MCP server, offering features such as automatic fixes, watch mode, and token consumption statistics, and supports 16 AI tools and 8 MCP clients.

Open website

About this tool

Purpose

ctxlint is used to check AI agent context files (such as CLAUDE.md, AGENTS.md, .cursorrules, etc.) as well as MCP server configuration files, ensuring they stay consistent with the codebase. When files are renamed, build scripts change, or the testing framework switches, these context files easily become outdated, causing AI agents to perform tasks based on incorrect information. ctxlint can detect such problems in advance.

Main capabilities

  • Context file checking: Detects broken paths, incorrect commands, outdated references, and contradictions between files.
  • MCP configuration checking: Scans configuration files such as .mcp.json, uncovering issues such as hardcoded API keys, invalid references, and deprecated fields.
  • Session auditing: Optionally audits agent session history and memory entries, checking cross-project consistency and missing settings.
  • Token awareness: Shows the context window size consumed by context files and flags redundant content.
  • Automatic fixes: Via the --fix parameter, uses Git history to automatically rewrite broken paths.
  • Multiple output formats: Supports text, JSON, and SARIF (for GitHub code scanning).
  • MCP server: Provides 7 tools (ctxlint_audit, ctxlint_mcp_audit, ctxlint_session_audit, ctxlint_skill_audit, ctxlint_validate_path, ctxlint_token_report, ctxlint_fix), which can be integrated with IDEs or agents.
  • Watch mode: The --watch parameter automatically rechecks when context files change.
  • Broad support: Covers 16 AI tools including Claude Code, Cursor, Copilot, Windsurf, Gemini, Cline, Aider, and 8 MCP clients.

Usage

Run directly without installation:

npx ctxlint

Project installation (recommended for teams):

npm install --save-dev ctxlint

Add to package.json scripts:

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

Or make it globally available in every project without installing it per project.

Common options:

  • --strict: Enforce in CI (non-strict mode always exits 0).
  • --fix: Automatically fix broken paths.
  • --watch: Watch for file changes and recheck.
  • --mcp: Enable MCP configuration checking.
  • --mcp-global: Additionally scan global MCP configurations (Claude Desktop, Cursor, Windsurf, Amazon Q).
  • --session: Enable session checking (optional, accesses files outside the project directory).
  • --skills: Enable skill checking.
  • --config <path>: Specify the configuration file location.
  • --no-ignore-file: Skip ignore files for this run.

Configuration file: Create .ctxlintrc or .ctxlintrc.json。

{
  "contextFiles": ["CONVENTIONS.md"],
  "exclude": ["test/fixtures/**"]
}

in the project root directory

Ignore file:.ctxlintignore, each line in the format checkName [fileGlob] [# reason], used to suppress specific findings.

For the MCP server:

npx ctxlint serve

Or configure in .mcp.json :

{
  "mcpServers": {
    "ctxlint": {
      "command": "npx",
      "args": ["ctxlint", "serve"]
    }
  }
}

CI integration: Supports SARIF output for GitHub code scanning, and can be set up as a pre-commit hook or pre-commit framework.

Applicable scenarios

  • When a development team maintains multiple AI context files and MCP configurations.
  • To automatically check consistency of context files in a CI process.
  • To prevent outdated context files from entering the repository before code is committed through a Git hook.
  • To serve as an MCP server for an IDE or AI agent to call, validating paths and configurations in real time.

Limitations

  • Session checking is an optional feature because it requires access to files outside the project directory (such as agent history records under the user's home directory, or sibling repositories in parent directories).
  • In non-strict mode it always exits 0, and is enforced in CI only through --strict.
  • A complete list of all 16 supported AI tools and 8 MCP clients, charging models, prices, and other information is not yet provided.
  • The installation package size is about 400 KB (tarball), with zero runtime dependencies.

Specification

ctxlint is the reference implementation of four open specifications, including the context checking specification, MCP configuration checking specification, session checking specification, and skill checking specification, all of which provide machine-readable rule catalogs that any linter, IDE extension, or CI system can implement.

Related tools

Browse category