ctxlint

ctxlint

只需单击一次，即可将其添加到本地 Yaw MCP 配置中，让它在每个 Yaw Terminal 会话中都可用。也可以按照下方说明手动安装。

针对实际代码库检查 AI Agent 上下文文件、MCP 服务配置和会话数据。 上下文检查 + MCP 配置检查 + 会话审计。支持 16 种 AI 工具、8 种 MCP 客户端、跨项目一致性检查和自动修复。可用作命令行工具、CI 步骤、提交前钩子或 MCP 服务。

你的 CLAUDE.md 正在误导 Agent。你的 .mcp.json 里有硬编码的 API 密钥。ctxlint 能同时发现这两个问题。

为什么选择 ctxlint？

每种 AI 编码工具都会提供一个上下文文件：CLAUDE.md、.cursorrules、AGENTS.md、.mcp.json。这些文件是你与 Agent 之间最重要的接口——它们会告诉 Agent 要构建什么、如何测试以及文件位于何处。

但上下文文件很容易过时。你重命名文件、更改构建脚本，或者从 Jest 切换到 Vitest，而 CLAUDE.md 仍写着旧内容。Agent 会忠实地遵循这些过时指令，然后失败。你花 10 分钟排查问题，最后才发现 Markdown 文件第 12 行的路径写错了。

想象一个团队有 5 个上下文文件、3 份 MCP 配置，还有 2 个人上周修改过构建系统——问题就会变得很棘手，而目前没有现成的解决方案。

ctxlint 是专为此用途打造的代码检查工具。它会读取上下文文件，并与实际代码库交叉比对，在 Agent 发现问题之前找出其中的偏差。

• 即时启动——以单个自包含包的形式发布，无运行时依赖。npx 下载约 400 KB 的压缩包后即可立即启动
• 发现实际问题——损坏的路径、错误的命令、过时的引用以及文件间的矛盾
• 智能建议——检测 Git 重命名并进行模糊匹配，推荐正确路径
• 自动修复——--fix 使用 Git 历史自动改写损坏的路径
• 感知令牌数量——显示文件占用的上下文窗口大小，并标记冗余内容
• 支持各种 AI 工具——支持 Claude Code、Cursor、Copilot、Windsurf、Gemini、Cline、Aider 等另外 9 种工具
• 多种输出格式——文本、JSON 和 SARIF（GitHub 代码扫描）
• MCP 服务——提供 7 个工具用于 IDE/Agent 集成，并带有可自动批准的工具注解
• 监视模式——使用 --watch 在上下文文件更改时自动重新检查

安装

直接运行（无需安装）：

npx -y @yawlabs/ctxlint@latest

项目安装（推荐团队使用）

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

然后将以下内容添加到 package.json 脚本中：

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

全局安装

npm install -g @yawlabs/ctxlint

如果希望 ctxlint 无需在每个项目中单独配置，即可在所有项目中使用，这种方式会很方便。

检查内容

检查项	检查内容
路径失效	上下文中引用了项目中不存在的文件
命令错误	构建／测试命令与 package.json 脚本或 Makefile 目标不符，以及构建未声明的 Gradle 项目路径或 Maven -pl 模块
上下文过时	近期代码更改后未更新的上下文文件
Token 浪费	每个会话中，文件占用多少上下文窗口
冗余内容	Agent 已能自行推断的内容（例如，react 已列在 package.json 中，却写着“我们使用 React”）
内容矛盾	上下文文件中的指令互相冲突（例如，一个文件要求“使用 Jest”，另一个则要求“使用 Vitest”）
Frontmatter	Cursor .mdc、Copilot 指令和 Windsurf 规则中的 YAML frontmatter 无效或缺失
CI 覆盖情况	.github/workflows/ 中未在任何上下文文件中说明的发布／部署工作流
CI 密钥	CI 工作流中使用（${{ secrets.X }}）但未在上下文文件中提及的密钥
内联密钥	粘贴到上下文文件中的真实密钥——私钥标头，以及符合 AWS/GitHub/Anthropic/OpenAI/npm/Slack/Google/Stripe Token 格式的字符串。消息绝不会回显密钥（仅显示脱敏后的 6 个字符前缀）
失效钩子	.claude/settings.json 中指向已不存在脚本的 PreToolUse 钩子／权限条目（失效的门禁会静默地不执行）。默认扫描项目的 .claude/settings.json[.local]；传入 --hooks-global 还会扫描用户全局的 ~/.claude/settings.json
缺少的密钥	已设置在同级仓库、但当前项目中缺失的 GitHub 密钥
配置分歧	在同级项目间发生偏离的规范配置文件（CI、tsconfig 等）
缺少的工作流	存在于 2 个或更多同级项目、但此处缺失的 GitHub Actions 工作流
过时记忆	引用了已不存在路径的 Claude Code 记忆条目
重复记忆	各项目间近似重复的记忆（内容重叠超过 60%）
循环检测	Agent 陷入循环——会话历史中重复执行命令或出现循环模式
记忆溢出	MEMORY.md 超过 Claude Code 会话加载上限（200 行／25KB）——超出上限的条目对 Agent 不可见
共享临时路径	Agent 写入并随后读取的固定临时路径（例如 /tmp/pkg.bak）——任何并发会话都可能在此期间覆盖它
未验证的门禁	lint／类型检查／测试／构建运行出错或没有输出，随后 Agent 却声称运行通过
直接修改默认分支	在 main／master 上修改了 10 个或更多文件，期间没有提交或切换分支
无法解析的 SHA	记忆中引用的提交 SHA 在此仓库中无法解析
大量读取	整文件读取超过 4,000 个 Token，并估算后续轮次将作为缓存上下文重新发送的 Token 数量（信息级基线）

支持的上下文文件

文件	工具
CLAUDE.md、CLAUDE.local.md、.claude/rules/*.md	Claude Code
AGENTS.md、AGENT.md、AGENTS.override.md	AAIF / Multi-agent 标准
.cursorrules、.cursor/rules/*.md、.cursor/rules/*.mdc、.cursor/rules/*/RULE.md	Cursor
.github/copilot-instructions.md、.github/instructions/*.md、.github/git-commit-instructions.md	GitHub Copilot
.windsurfrules、.windsurf/rules/*.md	Windsurf
GEMINI.md	Gemini CLI
.clinerules	Cline
.aiderules	Aider
.aide/rules/*.md	Aide / Codestory
.amazonq/rules/*.md	Amazon Q Developer
.goose/instructions.md、.goosehints	Goose by Block
.junie/guidelines.md、.junie/AGENTS.md	JetBrains Junie
.aiassistant/rules/*.md	JetBrains AI Assistant
.continuerules、.continue/rules/*.md	Continue
.rules	Zed
replit.md	Replit

MCP 服务配置检查

ctxlint 也会检查 MCP 服务配置文件——这些 JSON 配置用于告知 AI 客户端要连接哪些工具。它们也是上下文接口：决定了你的 Agent 能做什么。

# 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

扫描的 MCP 配置文件

文件	客户端
.mcp.json	Claude Code（通用项目配置）
.cursor/mcp.json	Cursor
.vscode/mcp.json	VS Code / GitHub Copilot
.amazonq/mcp.json	Amazon Q Developer
.continue/mcpServers/*.json	Continue

使用 --mcp-global 时，还会扫描 Claude Desktop、Cursor、Windsurf 和 Amazon Q 的全局配置。

MCP 配置检查能发现的问题

检查项	检查内容
架构	无效的 JSON、错误的根键（servers 而不是 mcpServers）、缺少必需字段
安全性	Git 跟踪的配置文件中硬编码的 API 密钥和 Bearer 令牌
命令	Windows 上 npx 缺少 cmd /c 包装、参数中的文件路径无效
已弃用	使用 SSE 传输（已于 2025 年 3 月弃用，请使用 Streamable HTTP）
环境变量	客户端的环境变量语法错误（${VAR} 与 ${env:VAR} 与 ${{ secrets.VAR }}）
URL	格式错误的 URL、项目配置中的 localhost、缺少路径组成部分
一致性	同一服务在不同客户端配置中的配置不一致
冗余	已禁用的服务、多个作用域中相同的配置

MCP 配置输出示例

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 配置 lint 规范

MCP 配置 lint 规则的完整规范、跨客户端配置概况以及机器可读的规则目录，均以开放规范的形式发布：

• MCP_CONFIG_LINT_SPEC.md — 完整的 lint 规则集（规则数量见规范系列表）、完整的客户端／格式参考以及实现指南。与工具无关，任何 lint 工具均可实现。
• mcp-config-lint-rules.json — 供 AI Agent、CI 系统和其他工具以编程方式使用的机器可读规则目录。

会话 lint

ctxlint 可以审查 AI Agent 会话数据（历史文件和记忆条目），检查跨项目一致性。会话检查会将当前项目与同级仓库进行比较，以发现配置偏差和缺少的设置。

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

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

会话检查默认不启用，因为它们会访问项目目录之外的文件（主目录中的 Agent 历史记录、父目录中的同级仓库）。

扫描哪些会话文件

Agent	历史记录	记忆
Claude Code	~/.claude/history.jsonl	~/.claude/projects/*/memory/*.md
Codex CLI	~/.codex/history.jsonl	—

用于判断 Agent 执行了哪些操作（运行的命令、写入或读取的文件）的检查，也会读取当前项目的 Claude Code 会话记录 ~/.claude/projects/<encoded-project>/*.jsonl，范围限制为最近 5 条。

会话检查能发现什么

检查项	检查内容
缺少机密	gh secret set 已在 2 个或更多同级仓库中运行，但未在此仓库中运行
配置分歧	共享配置文件（CI 工作流、tsconfig、.prettierrc 等）的行重叠率为 20-90%——足以表明彼此相关，但差异也足以说明它们正在偏离
缺少工作流	2 个或更多同级仓库中存在 GitHub Actions 工作流，但此项目中没有
过期记忆	引用了已不存在的文件路径的记忆条目
重复记忆	不同项目间近乎重复的记忆条目（重叠率 >60%）
循环检测	Agent 陷入循环——连续 3 次或更多次执行相同命令，或出现 A、B、A、B 这样的循环模式
记忆索引溢出	MEMORY.md 超出 Claude Code 文档所述的 200 行 / 25KB 会话加载上限，因此超出上限的条目对 Agent 不可见
共享临时路径	Agent 写入并在之后读回的固定临时路径（例如 /tmp/pkg.bak）——任何并发会话都可能在两次操作之间覆盖该路径
未经验证却声称通过的门禁	lint／类型检查／测试／构建运行出错或未输出任何内容，之后 Agent 却声称已通过
在默认分支上编辑	在 main/master 上编辑了 10 个或更多文件，中间没有提交或切换分支
无法解析的 SHA	记忆引用的提交 SHA 在此仓库中无法解析
大文件读取	整个文件的读取量达到 4,000 个或更多 token，并估算后续轮次将作为缓存上下文重新发送的 token 数（信息级基线）

会话 Lint 规范

• AGENT_SESSION_LINT_SPEC.md ——完整的 lint 规则集（规则数量见 Specifications 系列的表格）、涵盖 8 种 Agent 的 Agent 会话数据概况、同级项目检测策略和实现指南。
• agent-session-lint-rules.json ——机器可读的规则目录。

输出示例

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)

选项

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)

可用检查项： 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

传入任何 mcp-* 检查项名称都会隐含启用 --mcp。传入任何 session-* 检查项名称都会隐含启用 --session。传入任何 skill-* 检查项名称都会隐含启用 --skills。

监视模式

npx @yawlabs/ctxlint@latest --watch

每当上下文文件、MCP 配置或 package.json 发生更改时，都会自动重新运行 lint。在开发过程中，你可以一边编辑上下文文件，一边编写代码，这很有用。

在 CI 中使用

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

退出代码

代码	含义
0	成功——没有问题，或问题未达到严格模式的阈值
1	严格模式检测到至少一个错误或警告（已设置 --strict）
2	配置错误、无效的 CLI 选项或内部故障

在非严格模式下，ctxlint 始终以 0 退出——默认情况下，它只是一个报告工具。在 CI 中强制检查时，请传入 --strict。

GitHub Action

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

也可以使用以下选项：

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

SARIF 输出（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

自动修复

npx @yawlabs/ctxlint@latest --fix

如果损坏的路径在 git 中被重命名，或在项目中存在相近的匹配项，--fix 会自动重写上下文文件。

预提交钩子

内置

npx @yawlabs/ctxlint@latest init

设置一个 git 预提交钩子，在每次提交前运行 ctxlint --strict。

pre-commit 框架

在 .pre-commit-config.yaml 中添加：

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

配置文件

在项目根目录中创建 .ctxlintrc 或 .ctxlintrc.json：

{
  "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/**"]
}

contextFiles 数组会添加自定义文件模式，与内置列表中的文件一同扫描。对于 CONVENTIONS.md 等项目专属的上下文文件，这很有用。

exclude 数组用于排除上下文文件：其中的 glob 模式会让文件完全不参与扫描。可用于排除并非本项目 Agent 上下文的文件，例如测试样例、示例项目和 vendored 模板。

exclude 排除的是文件，而 ignore / ignoreRules / .ctxlintignore 抑制的是发现的问题。对于跨文件检查，这一区别很重要：contradictions 和 redundancy/duplicate-content 会比较发现的文件集，并将问题报告到字面上的 (project) 路径，而任何针对单个文件的 glob 都无法匹配该路径。要忽略两个本就不希望参与 lint 的文件之间的冲突，唯一的方法就是排除这些文件。如果真实的上下文文件有一个不重要的问题，请使用 .ctxlintignore；如果文件本就不应该纳入检查范围，请使用 exclude。

配置参考

字段	类型	默认值	含义
checks	string[]	所有检查	要运行的检查。检查名称包括 paths、commands、tokens、tier-tokens、redundancy、contradictions、frontmatter、staleness、ci-coverage、ci-secrets、content-secrets、hook-coverage，以及所有 mcp-* / session-* / skill-*。
ignore	string[]	[]	要跳过的检查，在 checks 之后评估。
ignoreRules	object[]	[]	按发现项抑制，粒度比 ignore 更细：每条规则只会删除与其匹配的发现项，并以首条匹配规则为准。未触发的规则以及缺少 reason 的规则会列在文本报告和 JSON _meta.ignoreReport 中。
ignoreRules[].check	string	必填	规则适用的检查，使用精确名称（paths、session-stale-memory 等）。
ignoreRules[].match	string	无	对发现项消息进行匹配的正则表达式。如果规则既没有 match 也没有 pathPattern，则会删除该检查的所有发现项；两者都有时，必须同时匹配。
ignoreRules[].pathPattern	string	无	对发现项提及的每个路径进行匹配的正则表达式；只有所有路径都匹配时，规则才会触发。仅适用于 session-stale-memory：用于其他检查时，规则不会触发，且加载配置时会打印警告。
ignoreRules[].reason	string	无	抑制该发现项的原因。可选，但没有原因的规则会列在报告中以供审查。
strict	boolean	false	存在任何警告或错误时以非零状态退出。
tokenThresholds	object	见下文	单文件和跨文件的 token 阈值。
tokenThresholds.info	number	1000	tokens/info 的单文件提示阈值。
tokenThresholds.warning	number	3000	tokens/large 的单文件警告阈值。
tokenThresholds.error	number	8000	tokens/excessive 的单文件错误阈值。
tokenThresholds.aggregate	number	5000	tokens/aggregate 的跨文件总量阈值。
tokenThresholds.tierBreakdown	number	1000	tier-tokens/section-breakdown 的始终加载文件阈值。
tokenThresholds.tierAggregate	number	4000	tier-tokens/aggregate 的始终加载合计阈值。
contextFiles	string[]	[]	与内置列表一起扫描的额外 glob 模式。
exclude	string[]	[]	从扫描中完全排除上下文文件的 glob 模式，与每个文件相对于项目的路径进行匹配。此操作会移除文件，而非抑制发现项，因此被排除的文件也不会参与跨文件检查。
mcp	boolean	false	默认启用 MCP 配置检查（与 --mcp 相同）。
mcpOnly	boolean	false	仅运行 MCP 配置检查，跳过上下文文件检查（与 --mcp-only 相同）。
mcpGlobal	boolean	false	同时扫描用户/全局 MCP 配置（与 --mcp-global 相同）。
session	boolean	false	启用会话审计检查（跨项目一致性）；与 --session 相同。
sessionOnly	boolean	false	仅运行会话检查，跳过上下文和 MCP 检查（与 --session-only 相同）。
skills	boolean	false	启用 Agent 技能检查（~/.claude/skills + ~/.claude/agents）；与 --skills 相同。
skillsOnly	boolean	false	仅运行 Agent 技能检查，跳过其他所有检查（与 --skills-only 相同）。
hooksGlobal	boolean	false	在失效钩子检查中同时扫描用户全局 ~/.claude/settings.json（与 --hooks-global 相同）。
配置文件的解析顺序：项目根目录中的 .ctxlintrc → .ctxlintrc.json。使用 --config <path> 指定其他位置。CLI 标志会覆盖配置文件字段。

CLI 标志会覆盖配置文件设置。使用 --config <path> 从自定义位置加载配置。

忽略文件（.ctxlintignore）

项目根目录中的 .ctxlintignore 文件可在不修改 .ctxlintrc 的情况下抑制检查结果。每行一条规则，格式为 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 是 选项下可用检查列表中的名称（paths、tokens、mcp-security……），而不是规则 ID。名称不是检查项时不会被拒绝：该规则永远不会匹配，因此会被报告为从未触发。
• fileGlob 是可选项。未指定时，规则适用于所有文件。指定后，规则仅适用于路径匹配的文件中的检查结果 — ctxlint 打印的项目相对路径，在所有平台上都使用正斜杠，并包含点文件。contradictions 和 redundancy/duplicate-content 产生的跨文件检查结果会标记为路径 (project)；使用该字面值进行匹配（contradictions (project)）。
• # reason 前需要有一个空格。在 paths#legacy 中，整个标记会被读取为检查名称。系统只读取前两个标记，因此这里不支持消息正则表达式；请改用 ignoreRules。
• 带 glob 的规则会先按文件顺序应用，然后应用不带 glob 的规则以及 ignoreRules。检查结果会被第一条匹配的规则丢弃。
• 被丢弃的数量、未丢弃任何内容的规则，以及未提供原因的规则，都会与 ignoreRules 一同列在“忽略规则”报告中。
• --no-ignore-file 会在本次运行中跳过该文件；ignoreRules 仍会生效。文件更改时，--watch 会重新运行 lint 检查。

用作 MCP 服务

ctxlint 内置了一个 MCP 服务，提供七种工具（ctxlint_audit、ctxlint_mcp_audit、ctxlint_session_audit、ctxlint_skill_audit、ctxlint_validate_path、ctxlint_token_report、ctxlint_fix）。所有只读工具都会声明注释，以便 MCP 客户端跳过确认对话框。

使用 serve 子命令启动（或使用等效的 --mcp-server 标志，该标志为保持向后兼容而保留）：

npx -y @yawlabs/ctxlint@latest serve

使用 Claude Code

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

使用 .mcp.json（Claude Code 项目配置、Cursor、Windsurf）

在项目根目录中创建 .mcp.json：

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"]
    }
  }
}

提示： 此文件可以安全地提交到代码仓库 — 其中不包含机密信息。

使用 VS Code / GitHub Copilot

添加到 .vscode/mcp.json：

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

使用 Claude Desktop

添加到 Claude Desktop 配置文件（claude_desktop_config.json）：

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

JSON 输出

npx @yawlabs/ctxlint@latest --format json

返回包含所有文件检查结果、问题和摘要的结构化 JSON — 适用于构建集成或仪表板。

规范

ctxlint 是四项用于 lint AI Agent 接口的开放规范的参考实现。这些规范与工具无关，任何 linter、IDE 扩展或 CI 系统都可以实现它们。

规范	涵盖内容
AI 上下文文件 Lint 规范	43 条规则，用于验证 16 个客户端中的上下文文件（CLAUDE.md、.cursorrules、AGENTS.md 等）。涵盖文件格式、frontmatter 架构、路径/命令验证、过时内容、token 预算、冗余和矛盾。
MCP 配置 Lint 规范	29 条规则，用于验证 8 个客户端中的 MCP 服务配置（.mcp.json、.cursor/mcp.json、.vscode/mcp.json 等）。涵盖架构验证、硬编码密钥、环境变量语法、已弃用的传输方式和跨文件一致性。
Agent 会话 Lint 规范	13 条规则，用于审计 8 个 Agent 的会话数据（历史记录、记忆）。涵盖跨项目密钥一致性、配置偏移、过时记忆和循环检测。
Agent 技能 Lint 规范	5 条规则，用于审计 ~/.claude 下的 Claude Code 技能（SKILL.md）和 Agent（.md）定义。涵盖 frontmatter 是否存在、失效引用、触发短语冲突、孤立技能和失效的工具限制。（v1，实验性）

所有规范都包含可供程序读取的机器可读规则目录：

• context-lint-rules.json — 上下文文件规则和 16 种受支持的格式定义
• mcp-config-lint-rules.json — MCP 配置规则和 8 种客户端定义
• agent-session-lint-rules.json — 会话 lint 规则和 8 种 Agent 数据源定义
• agent-skill-lint-rules.json — Agent 技能 lint 规则（~/.claude/skills、~/.claude/agents）

Yaw Labs 的其他产品

• Yaw — AI 原生终端

许可证

MIT