@yawlabs/ctxlint 0.13.2 → 0.13.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/.pre-commit-hooks.yaml +1 -1
  2. package/README.md +568 -568
  3. package/dist/index.js +127 -60
  4. package/mcph-config-lint-rules.json +11 -11
  5. package/package.json +1 -1
package/README.md CHANGED
@@ -1,568 +1,568 @@
1
- # ctxlint
2
-
3
- [![npm version](https://img.shields.io/npm/v/@yawlabs/ctxlint)](https://www.npmjs.com/package/@yawlabs/ctxlint)
4
- [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
5
- [![GitHub stars](https://img.shields.io/github/stars/YawLabs/ctxlint)](https://github.com/YawLabs/ctxlint/stargazers)
6
- [![CI](https://github.com/YawLabs/ctxlint/actions/workflows/ci.yml/badge.svg)](https://github.com/YawLabs/ctxlint/actions/workflows/ci.yml)
7
- [![Release](https://github.com/YawLabs/ctxlint/actions/workflows/release.yml/badge.svg)](https://github.com/YawLabs/ctxlint/actions/workflows/release.yml)
8
- [![MCP Compliance](https://raw.githubusercontent.com/YawLabs/ctxlint/main/compliance-badge.svg)](https://github.com/YawLabs/mcp-compliance)
9
-
10
- **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.
11
-
12
- Your `CLAUDE.md` is lying to your agent. Your `.mcp.json` has a hardcoded API key. ctxlint catches both.
13
-
14
- [![Add to Yaw MCP](https://yaw.sh/yaw-mcp-button.svg)](https://yaw.sh/mcp/install?name=ctxlint&command=npx&args=-y%2C%40yawlabs%2Fctxlint%2Cserve&description=Lint%20AI%20agent%20context%20files%20and%20MCP%20configs%20against%20your%20codebase&source=https%3A%2F%2Fgithub.com%2FYawLabs%2Fctxlint)
15
-
16
- One click adds this to your local Yaw MCP config so it's available in every Yaw Terminal session. Or install manually below.
17
-
18
- ## Why ctxlint?
19
-
20
- 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.
21
-
22
- 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.
23
-
24
- 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.
25
-
26
- 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.
27
-
28
- - **Instant startup** — ships as a single self-contained bundle with zero runtime dependencies. `npx` downloads a ~400 KB tarball and starts immediately
29
- - **Catches real problems** — broken paths, wrong commands, stale references, contradictions across files
30
- - **Smart suggestions** — detects git renames and fuzzy-matches to suggest the right path
31
- - **Auto-fix** — `--fix` rewrites broken paths automatically using git history
32
- - **Token-aware** — shows how much context window your files consume and flags redundant content
33
- - **Every AI tool** — supports Claude Code, Cursor, Copilot, Windsurf, Gemini, Cline, Aider, and 9 more
34
- - **Multiple outputs** — text, JSON, and SARIF (GitHub Code Scanning)
35
- - **MCP server** — 7 tools for IDE/agent integration with tool annotations for auto-approval
36
- - **Watch mode** — `--watch` re-lints automatically when context files change
37
-
38
- ## Install
39
-
40
- Run directly (no install needed):
41
-
42
- ```bash
43
- npx -y @yawlabs/ctxlint@latest
44
- ```
45
-
46
- ### Project install (recommended for teams)
47
-
48
- ```bash
49
- npm install -D @yawlabs/ctxlint
50
- # or
51
- pnpm add -D @yawlabs/ctxlint
52
- ```
53
-
54
- Then add to your `package.json` scripts:
55
-
56
- ```json
57
- {
58
- "scripts": {
59
- "lint:ctx": "ctxlint --strict"
60
- }
61
- }
62
- ```
63
-
64
- ### Global install
65
-
66
- ```bash
67
- npm install -g @yawlabs/ctxlint
68
- ```
69
-
70
- Useful if you want `ctxlint` available in every project without per-project setup.
71
-
72
- ## What It Checks
73
-
74
- | Check | What it finds |
75
- | --------------------- | --------------------------------------------------------------------------------------------- |
76
- | **Broken paths** | File references in context that don't exist in your project |
77
- | **Wrong commands** | Build/test commands that don't match your package.json scripts or Makefile targets |
78
- | **Stale context** | Context files not updated after recent code changes |
79
- | **Token waste** | How much context window your files consume per session |
80
- | **Redundancy** | Content the agent can already infer (e.g. "We use React" when react is in package.json) |
81
- | **Contradictions** | Conflicting directives across context files (e.g. "use Jest" in one, "use Vitest" in another) |
82
- | **Frontmatter** | Invalid or missing YAML frontmatter in Cursor .mdc, Copilot instructions, and Windsurf rules |
83
- | **CI coverage** | Release/deploy workflows in `.github/workflows/` not documented in any context file |
84
- | **CI secrets** | Secrets used in CI workflows (`${{ secrets.X }}`) not mentioned in context files |
85
- | **Dead hooks** | PreToolUse hooks / permissions entries in `.claude/settings.json` pointing at scripts that no longer exist (a dead gate silently no-ops). Scans project `.claude/settings.json[.local]` by default; pass `--hooks-global` to also scan the user-global `~/.claude/settings.json` |
86
- | **Missing secrets** | GitHub secrets set on sibling repos but missing from current project |
87
- | **Diverged configs** | Canonical config files (CI, tsconfig, etc.) drifting across sibling projects |
88
- | **Missing workflows** | GitHub Actions workflows present in 2+ siblings but absent here |
89
- | **Stale memory** | Claude Code memory entries referencing paths that no longer exist |
90
- | **Duplicate memory** | Near-duplicate memories across projects (>60% content overlap) |
91
- | **Loop detection** | Agent stuck in loops — repeated commands or cyclic patterns in session history |
92
-
93
- ## Supported Context Files
94
-
95
- | File | Tool |
96
- | ---------------------------------------------------------------------------------------------------- | --------------------------- |
97
- | `CLAUDE.md`, `CLAUDE.local.md`, `.claude/rules/*.md` | Claude Code |
98
- | `AGENTS.md`, `AGENT.md`, `AGENTS.override.md` | AAIF / Multi-agent standard |
99
- | `.cursorrules`, `.cursor/rules/*.md`, `.cursor/rules/*.mdc`, `.cursor/rules/*/RULE.md` | Cursor |
100
- | `.github/copilot-instructions.md`, `.github/instructions/*.md`, `.github/git-commit-instructions.md` | GitHub Copilot |
101
- | `.windsurfrules`, `.windsurf/rules/*.md` | Windsurf |
102
- | `GEMINI.md` | Gemini CLI |
103
- | `.clinerules` | Cline |
104
- | `.aiderules` | Aider |
105
- | `.aide/rules/*.md` | Aide / Codestory |
106
- | `.amazonq/rules/*.md` | Amazon Q Developer |
107
- | `.goose/instructions.md`, `.goosehints` | Goose by Block |
108
- | `.junie/guidelines.md`, `.junie/AGENTS.md` | JetBrains Junie |
109
- | `.aiassistant/rules/*.md` | JetBrains AI Assistant |
110
- | `.continuerules`, `.continue/rules/*.md` | Continue |
111
- | `.rules` | Zed |
112
- | `replit.md` | Replit |
113
-
114
- ## MCP Server Config Linting
115
-
116
- 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.
117
-
118
- ```bash
119
- # Lint context files + MCP configs
120
- npx @yawlabs/ctxlint@latest --mcp
121
-
122
- # Lint only MCP configs
123
- npx @yawlabs/ctxlint@latest --mcp-only
124
-
125
- # Include global/user-level configs (Claude Desktop, Cursor, Windsurf, etc.)
126
- npx @yawlabs/ctxlint@latest --mcp-global
127
- ```
128
-
129
- ### What MCP config files are scanned
130
-
131
- | File | Client |
132
- | ----------------------------- | -------------------------------------- |
133
- | `.mcp.json` | Claude Code (universal project config) |
134
- | `.cursor/mcp.json` | Cursor |
135
- | `.vscode/mcp.json` | VS Code / GitHub Copilot |
136
- | `.amazonq/mcp.json` | Amazon Q Developer |
137
- | `.continue/mcpServers/*.json` | Continue |
138
-
139
- With `--mcp-global`, also scans Claude Desktop, Cursor, Windsurf, and Amazon Q global configs.
140
-
141
- ### What MCP config checks catch
142
-
143
- | Check | What it finds |
144
- | --------------- | -------------------------------------------------------------------------------------- |
145
- | **Schema** | Invalid JSON, wrong root key (`servers` vs `mcpServers`), missing required fields |
146
- | **Security** | Hardcoded API keys and Bearer tokens in git-tracked config files |
147
- | **Commands** | Missing `cmd /c` wrapper for npx on Windows, broken file paths in args |
148
- | **Deprecated** | SSE transport usage (deprecated March 2025, use Streamable HTTP) |
149
- | **Env vars** | Wrong env var syntax for the client (`${VAR}` vs `${env:VAR}` vs `${{ secrets.VAR }}`) |
150
- | **URLs** | Malformed URLs, localhost in project configs, missing path component |
151
- | **Consistency** | Same server configured differently across client configs |
152
- | **Redundancy** | Disabled servers, identical configs at multiple scopes |
153
-
154
- ### Example MCP config output
155
-
156
- ```
157
- MCP Configs
158
- .mcp.json
159
- ✗ mcp-security Server "api": hardcoded Bearer token in a git-tracked file
160
- ✗ mcp-deprecated Server "old-svc": SSE transport is deprecated — use "http"
161
- ✓ mcp-schema
162
- ✓ mcp-commands
163
- .cursor/mcp.json
164
- ✗ mcp-env Server "api": Cursor uses ${env:VAR}, not ${VAR}
165
- ✓ mcp-schema
166
- .vscode/mcp.json
167
- ✗ mcp-schema .vscode/mcp.json must use "servers" as root key, not "mcpServers"
168
-
169
- Cross-file
170
- ⚠ Server "api" is configured differently in .mcp.json and .cursor/mcp.json
171
- ℹ Server "db" is in .mcp.json but missing from .cursor/mcp.json
172
-
173
- Summary: 3 errors, 2 warnings, 1 info
174
- ```
175
-
176
- ### MCP Config Linting Specification
177
-
178
- The full specification for MCP config linting rules, the cross-client config landscape, and a machine-readable rule catalog are published as open specifications:
179
-
180
- - **[`MCP_CONFIG_LINT_SPEC.md`](./MCP_CONFIG_LINT_SPEC.md)** — the full lint-rule set (rule count in the [Specifications](#specifications) family table), the complete client/format reference, and implementation guidance. Tool-agnostic — any linter can implement it.
181
- - **[`mcp-config-lint-rules.json`](./mcp-config-lint-rules.json)** — Machine-readable rule catalog for programmatic consumption by AI agents, CI systems, and other tools.
182
-
183
- ## mcph Config Linting
184
-
185
- ctxlint also lints `.mcph.json` — the config file read by the [`@yawlabs/mcph`](https://github.com/YawLabs/mcph) CLI. Distinct from `.mcp.json` (different schema, different threat model). Applies across the user-global (`~/.mcph.json`), per-project (`.mcph.json`), and machine-local (`.mcph.local.json`) scope cascade.
186
-
187
- > **Note:** the mcph rule family (and the `ctxlint_mcph_audit` MCP tool) is **under review** — the upstream mcp.hosting platform is archived, so this family's future is being reassessed. The rules and tool still ship and work; only their long-term status is undecided.
188
-
189
- ```bash
190
- # Lint context files + .mcph.json
191
- npx @yawlabs/ctxlint@latest --mcph
192
-
193
- # Lint only .mcph.json
194
- npx @yawlabs/ctxlint@latest --mcph-only
195
-
196
- # Include the user-global ~/.mcph.json
197
- npx @yawlabs/ctxlint@latest --mcph-global
198
-
199
- # Treat any token in any .mcph.json as an error (env-var-only posture)
200
- npx @yawlabs/ctxlint@latest --mcph --mcph-strict-env-token
201
- ```
202
-
203
- ### What mcph config checks catch
204
-
205
- | Check | What it finds |
206
- | --------------------------- | ----------------------------------------------------------------------------------------------------------------- |
207
- | **mcph-token-security** | mcp.hosting PAT (`mcp_pat_*`) leaks, malformed tokens, and prefers env-var (`MCPH_TOKEN`) over file-stored tokens |
208
- | **mcph-apibase** | Invalid `apiBase` URLs and plaintext HTTP to public hosts (private hosts like `localhost` / RFC 1918 are exempt) |
209
- | **mcph-schema-conformance** | Unknown / typo'd fields and stale `version` numbers vs the current `mcph.config.v1.json` schema |
210
- | **mcph-lists** | Conflicts (entries in both `servers` allow-list and `blocked` deny-list) and duplicates within either list |
211
- | **mcph-gitignore** | `.mcph.local.json` not covered by `.gitignore` — machine-local overrides exist precisely to stay machine-local |
212
-
213
- ## Session Linting
214
-
215
- 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.
216
-
217
- ```bash
218
- # Lint context files + session data
219
- npx @yawlabs/ctxlint@latest --session
220
-
221
- # Lint only session data
222
- npx @yawlabs/ctxlint@latest --session-only
223
- ```
224
-
225
- 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).
226
-
227
- ### What session files are scanned
228
-
229
- | Agent | History | Memory |
230
- | ----------- | ------------------------- | ---------------------------------- |
231
- | Claude Code | `~/.claude/history.jsonl` | `~/.claude/projects/*/memory/*.md` |
232
- | Codex CLI | `~/.codex/history.jsonl` | — |
233
-
234
- ### What session checks catch
235
-
236
- | Check | What it finds |
237
- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
238
- | **Missing secrets** | `gh secret set` ran on 2+ sibling repos but not this one |
239
- | **Diverged configs** | Shared config files (CI workflows, tsconfig, .prettierrc, etc.) with 20-90% line overlap — enough to be related, different enough to be drifting |
240
- | **Missing workflows** | GitHub Actions workflows in 2+ siblings but absent from this project |
241
- | **Stale memory** | Memory entries referencing file paths that no longer exist |
242
- | **Duplicate memory** | Near-duplicate memory entries across projects (>60% overlap) |
243
- | **Loop detection** | Agent stuck in a loop — 3+ consecutive identical commands, or cyclic A,B,A,B patterns |
244
- | **Memory index overflow** | `MEMORY.md` exceeds Claude Code's documented 200-line / 25KB session-load cap, so entries past the cap are invisible to the agent |
245
-
246
- ### Session Linting Specification
247
-
248
- - **[`AGENT_SESSION_LINT_SPEC.md`](./AGENT_SESSION_LINT_SPEC.md)** — 8 lint rules, the agent session data landscape across 8 agents, sibling detection strategy, and implementation guidance.
249
- - **[`agent-session-lint-rules.json`](./agent-session-lint-rules.json)** — Machine-readable rule catalog.
250
-
251
- ## Example Output
252
-
253
- ```
254
- ctxlint v0.9.10
255
-
256
- Scanning /Users/you/my-app...
257
-
258
- Found 2 context files (1,847 tokens total)
259
- CLAUDE.md (1,203 tokens, 42 lines)
260
- AGENTS.md -> CLAUDE.md (symlink)
261
-
262
- CLAUDE.md
263
- ✗ Line 12: src/auth/middleware.ts does not exist
264
- → Did you mean src/middleware/auth.ts? (renamed 14 days ago)
265
- ✗ Line 8: "pnpm test" — script "test" not found in package.json
266
- ⚠ Last updated 47 days ago. src/routes/ has 8 commits since.
267
- ⚠ testing framework conflict: "Vitest" in CLAUDE.md vs "Jest" in AGENTS.md
268
- ℹ Line 3: "Express" is in package.json dependencies — agent can infer this
269
-
270
- Summary: 2 errors, 2 warnings, 1 info
271
- Token usage: 1,203 tokens per agent session
272
- Estimated waste: ~55 tokens (redundant content)
273
- ```
274
-
275
- ## Options
276
-
277
- ```
278
- Usage: ctxlint [options] [path]
279
-
280
- Arguments:
281
- path Project directory to scan (default: ".")
282
-
283
- Options:
284
- --strict Exit code 1 on any warning or error (for CI)
285
- --checks <list> Comma-separated checks to run (see below)
286
- --ignore <list> Comma-separated checks to skip
287
- --fix Auto-fix broken paths using git history and fuzzy matching
288
- --fix-dry-run Preview --fix changes without writing
289
- --yes Skip interactive confirmation prompts (required for --fix in TTY)
290
- --follow-symlinks Allow --fix to write through symlinks (default: skip)
291
- --format <fmt> Output format: text, json, or sarif (default: text)
292
- --tokens Show token breakdown per file
293
- --verbose Show passing checks too
294
- --quiet Suppress all output except errors (exit code only)
295
- --config <path> Path to config file (default: .ctxlintrc in project root)
296
- --depth <n> Max subdirectory depth to scan (default: 2)
297
- --mcp Enable MCP config linting alongside context file checks
298
- --mcp-only Run only MCP config checks, skip context file checks
299
- --mcp-global Also scan user/global MCP config files (implies --mcp)
300
- --mcph Enable .mcph.json (mcp.hosting CLI config) linting
301
- --mcph-only Run only mcph config checks
302
- --mcph-global Also scan ~/.mcph.json (implies --mcph)
303
- --mcph-strict-env-token Upgrade mcph-config/prefer-env-token from warning to error
304
- --session Enable session audit checks (cross-project consistency)
305
- --session-only Run only session checks, skip context and MCP checks
306
- --mcp-server Start the MCP server (alias: `serve` subcommand)
307
- --watch Re-lint on context file changes
308
- -V, --version Output the version number
309
- -h, --help Display help
310
-
311
- Commands:
312
- init Set up a git pre-commit hook
313
- ```
314
-
315
- **Available checks:** `paths`, `commands`, `staleness`, `tokens`, `tier-tokens`, `redundancy`, `contradictions`, `frontmatter`, `ci-coverage`, `ci-secrets`, `mcp-schema`, `mcp-security`, `mcp-commands`, `mcp-deprecated`, `mcp-env`, `mcp-urls`, `mcp-consistency`, `mcp-redundancy`, `mcph-token-security`, `mcph-apibase`, `mcph-schema-conformance`, `mcph-lists`, `mcph-gitignore`, `session-missing-secret`, `session-diverged-file`, `session-missing-workflow`, `session-stale-memory`, `session-duplicate-memory`, `session-loop-detection`, `session-memory-index-overflow`
316
-
317
- Passing any `mcp-*` check name implies `--mcp`. Passing any `mcph-*` check name implies `--mcph`. Passing any `session-*` check name implies `--session`.
318
-
319
- ## Watch Mode
320
-
321
- ```bash
322
- npx @yawlabs/ctxlint@latest --watch
323
- ```
324
-
325
- Re-lints automatically when any context file, MCP config, or `package.json` changes. Useful during development when you're editing context files alongside code.
326
-
327
- ## Use in CI
328
-
329
- ```yaml
330
- - name: Lint context files
331
- run: npx @yawlabs/ctxlint@latest --strict
332
- ```
333
-
334
- ### Exit Codes
335
-
336
- | Code | Meaning |
337
- | ---- | -------------------------------------------------------------------- |
338
- | `0` | Success — no issues, or issues below the strict threshold |
339
- | `1` | Strict mode caught at least one error or warning (`--strict` is set) |
340
- | `2` | Config error, invalid CLI option, or internal failure |
341
-
342
- In non-strict mode ctxlint always exits `0` — it's a reporting tool by default. Pass `--strict` to enforce in CI.
343
-
344
- ### GitHub Action
345
-
346
- ```yaml
347
- - name: Lint context files
348
- uses: yawlabs/ctxlint-action@v1
349
- ```
350
-
351
- Or with options:
352
-
353
- ```yaml
354
- - name: Lint context files
355
- uses: yawlabs/ctxlint-action@v1
356
- with:
357
- args: '--strict --mcp'
358
- ```
359
-
360
- ### SARIF Output (GitHub Code Scanning)
361
-
362
- ```yaml
363
- - name: Lint context files
364
- run: npx @yawlabs/ctxlint@latest --format sarif > ctxlint.sarif
365
-
366
- - name: Upload SARIF
367
- uses: github/codeql-action/upload-sarif@v3
368
- with:
369
- sarif_file: ctxlint.sarif
370
- ```
371
-
372
- ## Auto-fix
373
-
374
- ```bash
375
- npx @yawlabs/ctxlint@latest --fix
376
- ```
377
-
378
- When a broken path was renamed in git or has a close match in the project, `--fix` rewrites the context file automatically.
379
-
380
- ## Pre-commit Hook
381
-
382
- ### Built-in
383
-
384
- ```bash
385
- npx @yawlabs/ctxlint@latest init
386
- ```
387
-
388
- Sets up a git pre-commit hook that runs `ctxlint --strict` before each commit.
389
-
390
- ### pre-commit framework
391
-
392
- Add to your `.pre-commit-config.yaml`:
393
-
394
- ```yaml
395
- repos:
396
- - repo: https://github.com/yawlabs/ctxlint
397
- rev: v0.9.10
398
- hooks:
399
- - id: ctxlint
400
- ```
401
-
402
- ## Config File
403
-
404
- Create a `.ctxlintrc` or `.ctxlintrc.json` in your project root:
405
-
406
- ```json
407
- {
408
- "checks": ["paths", "commands", "tokens", "contradictions", "frontmatter"],
409
- "ignore": ["redundancy"],
410
- "strict": true,
411
- "tokenThresholds": {
412
- "info": 500,
413
- "warning": 2000,
414
- "error": 5000,
415
- "aggregate": 4000,
416
- "tierBreakdown": 1000,
417
- "tierAggregate": 4000
418
- },
419
- "contextFiles": ["CONVENTIONS.md", "docs/ai-rules.md"]
420
- }
421
- ```
422
-
423
- The `contextFiles` array adds custom file patterns to scan alongside the built-in list. Useful for project-specific context files like `CONVENTIONS.md`.
424
-
425
- ### Config Reference
426
-
427
- | Field | Type | Default | Meaning |
428
- | ------------------------------- | ---------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
429
- | `checks` | `string[]` | all checks | Checks to run. Check names include `paths`, `commands`, `tokens`, `tier-tokens`, `redundancy`, `contradictions`, `frontmatter`, `staleness`, `ci-coverage`, `ci-secrets`, plus any `mcp-*` / `session-*`. |
430
- | `ignore` | `string[]` | `[]` | Checks to skip, evaluated after `checks`. |
431
- | `strict` | `boolean` | `false` | Exit non-zero on any warning or error. |
432
- | `tokenThresholds` | `object` | see below | Per-file and cross-file token thresholds. |
433
- | `tokenThresholds.info` | `number` | `1000` | Per-file info threshold for `tokens/info`. |
434
- | `tokenThresholds.warning` | `number` | `3000` | Per-file warning threshold for `tokens/large`. |
435
- | `tokenThresholds.error` | `number` | `8000` | Per-file error threshold for `tokens/excessive`. |
436
- | `tokenThresholds.aggregate` | `number` | `5000` | Cross-file total threshold for `tokens/aggregate`. |
437
- | `tokenThresholds.tierBreakdown` | `number` | `1000` | Always-loaded file threshold for `tier-tokens/section-breakdown`. |
438
- | `tokenThresholds.tierAggregate` | `number` | `4000` | Combined always-loaded threshold for `tier-tokens/aggregate`. |
439
- | `contextFiles` | `string[]` | `[]` | Extra glob patterns to scan alongside the built-in list. |
440
- | `mcp` | `boolean` | `false` | Enable MCP config checks by default (same as `--mcp`). |
441
- | `mcpOnly` | `boolean` | `false` | Run only MCP config checks, skip context-file checks (same as `--mcp-only`). |
442
- | `mcpGlobal` | `boolean` | `false` | Also scan user/global MCP configs (same as `--mcp-global`). |
443
- | `mcph` | `boolean` | `false` | Enable `.mcph.json` (mcp.hosting CLI config) checks (same as `--mcph`). |
444
- | `mcphOnly` | `boolean` | `false` | Run only mcph config checks, skip context-file checks (same as `--mcph-only`). |
445
- | `mcphGlobal` | `boolean` | `false` | Also scan `~/.mcph.json` user-global config (same as `--mcph-global`). |
446
- | `mcphStrictEnvToken` | `boolean` | `false` | Upgrade `mcph-config/prefer-env-token` from warning to error (same as `--mcph-strict-env-token`). |
447
- | `session` | `boolean` | `false` | Enable session audit checks (cross-project consistency); same as `--session`. |
448
- | `sessionOnly` | `boolean` | `false` | Run only session checks, skip context and MCP checks (same as `--session-only`). |
449
-
450
- Config file resolution order: `.ctxlintrc` → `.ctxlintrc.json` in the project root. Use `--config <path>` to point elsewhere. CLI flags override config fields.
451
-
452
- CLI flags override config file settings. Use `--config <path>` to load a config from a custom location.
453
-
454
- ## Use as MCP Server
455
-
456
- ctxlint ships with an MCP server that exposes seven tools (`ctxlint_audit`, `ctxlint_mcp_audit`, `ctxlint_mcph_audit`, `ctxlint_session_audit`, `ctxlint_validate_path`, `ctxlint_token_report`, `ctxlint_fix`). All read-only tools declare annotations so MCP clients can skip confirmation dialogs.
457
-
458
- Launch it with the `serve` subcommand (or the equivalent `--mcp-server` flag, kept for back-compat):
459
-
460
- ```bash
461
- npx -y @yawlabs/ctxlint@latest serve
462
- ```
463
-
464
- ### With Claude Code
465
-
466
- ```bash
467
- claude mcp add ctxlint -- npx -y @yawlabs/ctxlint@latest serve
468
- ```
469
-
470
- ### With `.mcp.json` (Claude Code project config, Cursor, Windsurf)
471
-
472
- Create `.mcp.json` in your project root:
473
-
474
- macOS / Linux / WSL:
475
-
476
- ```json
477
- {
478
- "mcpServers": {
479
- "ctxlint": {
480
- "command": "npx",
481
- "args": ["-y", "@yawlabs/ctxlint@latest", "serve"]
482
- }
483
- }
484
- }
485
- ```
486
-
487
- Windows:
488
-
489
- ```json
490
- {
491
- "mcpServers": {
492
- "ctxlint": {
493
- "command": "cmd",
494
- "args": ["/c", "npx", "-y", "@yawlabs/ctxlint@latest", "serve"]
495
- }
496
- }
497
- }
498
- ```
499
-
500
- > **Tip:** This file is safe to commit — it contains no secrets.
501
-
502
- ### With VS Code / GitHub Copilot
503
-
504
- Add to `.vscode/mcp.json`:
505
-
506
- ```json
507
- {
508
- "servers": {
509
- "ctxlint": {
510
- "command": "npx",
511
- "args": ["-y", "@yawlabs/ctxlint@latest", "serve"]
512
- }
513
- }
514
- }
515
- ```
516
-
517
- ### With Claude Desktop
518
-
519
- Add to your Claude Desktop config (`claude_desktop_config.json`):
520
-
521
- ```json
522
- {
523
- "mcpServers": {
524
- "ctxlint": {
525
- "command": "npx",
526
- "args": ["-y", "@yawlabs/ctxlint@latest", "serve"]
527
- }
528
- }
529
- }
530
- ```
531
-
532
- ## JSON Output
533
-
534
- ```bash
535
- npx @yawlabs/ctxlint@latest --format json
536
- ```
537
-
538
- Returns structured JSON with all file results, issues, and summary — useful for building integrations or dashboards.
539
-
540
- ## Specifications
541
-
542
- 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.
543
-
544
- | Spec | What it covers |
545
- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
546
- | **[AI Context File Linting Spec](./CONTEXT_LINT_SPEC.md)** | 28 rules for validating context files (CLAUDE.md, .cursorrules, AGENTS.md, etc.) across 17 clients. Covers file formats, frontmatter schemas, path/command validation, staleness, token budgets, redundancy, and contradictions. |
547
- | **[MCP Config Linting Spec](./MCP_CONFIG_LINT_SPEC.md)** | 27 rules for validating MCP server configs (.mcp.json, .cursor/mcp.json, .vscode/mcp.json, etc.) across 8 clients. Covers schema validation, hardcoded secrets, env var syntax, deprecated transports, and cross-file consistency. |
548
- | **mcph Config Linting** (`mcph-config-lint-rules.json`) | 10 rules for validating `.mcph.json` — the config file read by the `@yawlabs/mcph` CLI. Covers PAT format + leakage, env-var posture, plaintext API endpoints, schema drift, and allow/deny list semantics across the scope cascade. |
549
- | **[Agent Session Linting Spec](./AGENT_SESSION_LINT_SPEC.md)** | 8 rules for auditing agent session data (history, memory) across 8 agents. Covers cross-project secret consistency, config drift, stale memory, and loop detection. |
550
- | **[Agent Skill Linting Spec](./AGENT_SKILL_LINT_SPEC.md)** | 5 rules for auditing Claude Code skill (`SKILL.md`) and agent (`.md`) definitions under `~/.claude`. Covers frontmatter presence, broken refs, trigger-phrase collisions, orphaned skills, and dead tool restrictions. (v1, experimental) |
551
-
552
- All specs include machine-readable rule catalogs for programmatic consumption:
553
-
554
- - [`context-lint-rules.json`](./context-lint-rules.json) — context file rules and 16 supported format definitions
555
- - [`mcp-config-lint-rules.json`](./mcp-config-lint-rules.json) — MCP config rules and 8 client definitions
556
- - [`mcph-config-lint-rules.json`](./mcph-config-lint-rules.json) — mcph CLI config rules (`.mcph.json`)
557
- - [`agent-session-lint-rules.json`](./agent-session-lint-rules.json) — session lint rules and 8 agent data source definitions
558
- - [`agent-skill-lint-rules.json`](./agent-skill-lint-rules.json) — agent-skill lint rules (`~/.claude/skills`, `~/.claude/agents`)
559
-
560
- ## Also By Yaw Labs
561
-
562
- - [Yaw](https://yaw.sh) — The AI-native terminal
563
- - [Spend](https://spend.sh) — AI spend tracking, cost estimation, and provider comparison across 10+ providers
564
- - [Token Limit News](https://tokenlimit.news) — Weekly AI dev tooling newsletter
565
-
566
- ## License
567
-
568
- MIT
1
+ # ctxlint
2
+
3
+ [![npm version](https://img.shields.io/npm/v/@yawlabs/ctxlint)](https://www.npmjs.com/package/@yawlabs/ctxlint)
4
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
5
+ [![GitHub stars](https://img.shields.io/github/stars/YawLabs/ctxlint)](https://github.com/YawLabs/ctxlint/stargazers)
6
+ [![CI](https://github.com/YawLabs/ctxlint/actions/workflows/ci.yml/badge.svg)](https://github.com/YawLabs/ctxlint/actions/workflows/ci.yml)
7
+ [![Release](https://github.com/YawLabs/ctxlint/actions/workflows/release.yml/badge.svg)](https://github.com/YawLabs/ctxlint/actions/workflows/release.yml)
8
+ [![MCP Compliance](https://raw.githubusercontent.com/YawLabs/ctxlint/main/compliance-badge.svg)](https://github.com/YawLabs/mcp-compliance)
9
+
10
+ **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.
11
+
12
+ Your `CLAUDE.md` is lying to your agent. Your `.mcp.json` has a hardcoded API key. ctxlint catches both.
13
+
14
+ [![Add to Yaw MCP](https://yaw.sh/yaw-mcp-button.svg)](https://yaw.sh/mcp/install?name=ctxlint&command=npx&args=-y%2C%40yawlabs%2Fctxlint%2Cserve&description=Lint%20AI%20agent%20context%20files%20and%20MCP%20configs%20against%20your%20codebase&source=https%3A%2F%2Fgithub.com%2FYawLabs%2Fctxlint)
15
+
16
+ One click adds this to your local Yaw MCP config so it's available in every Yaw Terminal session. Or install manually below.
17
+
18
+ ## Why ctxlint?
19
+
20
+ 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.
21
+
22
+ 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.
23
+
24
+ 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.
25
+
26
+ 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.
27
+
28
+ - **Instant startup** — ships as a single self-contained bundle with zero runtime dependencies. `npx` downloads a ~400 KB tarball and starts immediately
29
+ - **Catches real problems** — broken paths, wrong commands, stale references, contradictions across files
30
+ - **Smart suggestions** — detects git renames and fuzzy-matches to suggest the right path
31
+ - **Auto-fix** — `--fix` rewrites broken paths automatically using git history
32
+ - **Token-aware** — shows how much context window your files consume and flags redundant content
33
+ - **Every AI tool** — supports Claude Code, Cursor, Copilot, Windsurf, Gemini, Cline, Aider, and 9 more
34
+ - **Multiple outputs** — text, JSON, and SARIF (GitHub Code Scanning)
35
+ - **MCP server** — 7 tools for IDE/agent integration with tool annotations for auto-approval
36
+ - **Watch mode** — `--watch` re-lints automatically when context files change
37
+
38
+ ## Install
39
+
40
+ Run directly (no install needed):
41
+
42
+ ```bash
43
+ npx -y @yawlabs/ctxlint@latest
44
+ ```
45
+
46
+ ### Project install (recommended for teams)
47
+
48
+ ```bash
49
+ npm install -D @yawlabs/ctxlint
50
+ # or
51
+ pnpm add -D @yawlabs/ctxlint
52
+ ```
53
+
54
+ Then add to your `package.json` scripts:
55
+
56
+ ```json
57
+ {
58
+ "scripts": {
59
+ "lint:ctx": "ctxlint --strict"
60
+ }
61
+ }
62
+ ```
63
+
64
+ ### Global install
65
+
66
+ ```bash
67
+ npm install -g @yawlabs/ctxlint
68
+ ```
69
+
70
+ Useful if you want `ctxlint` available in every project without per-project setup.
71
+
72
+ ## What It Checks
73
+
74
+ | Check | What it finds |
75
+ | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
76
+ | **Broken paths** | File references in context that don't exist in your project |
77
+ | **Wrong commands** | Build/test commands that don't match your package.json scripts or Makefile targets |
78
+ | **Stale context** | Context files not updated after recent code changes |
79
+ | **Token waste** | How much context window your files consume per session |
80
+ | **Redundancy** | Content the agent can already infer (e.g. "We use React" when react is in package.json) |
81
+ | **Contradictions** | Conflicting directives across context files (e.g. "use Jest" in one, "use Vitest" in another) |
82
+ | **Frontmatter** | Invalid or missing YAML frontmatter in Cursor .mdc, Copilot instructions, and Windsurf rules |
83
+ | **CI coverage** | Release/deploy workflows in `.github/workflows/` not documented in any context file |
84
+ | **CI secrets** | Secrets used in CI workflows (`${{ secrets.X }}`) not mentioned in context files |
85
+ | **Dead hooks** | PreToolUse hooks / permissions entries in `.claude/settings.json` pointing at scripts that no longer exist (a dead gate silently no-ops). Scans project `.claude/settings.json[.local]` by default; pass `--hooks-global` to also scan the user-global `~/.claude/settings.json` |
86
+ | **Missing secrets** | GitHub secrets set on sibling repos but missing from current project |
87
+ | **Diverged configs** | Canonical config files (CI, tsconfig, etc.) drifting across sibling projects |
88
+ | **Missing workflows** | GitHub Actions workflows present in 2+ siblings but absent here |
89
+ | **Stale memory** | Claude Code memory entries referencing paths that no longer exist |
90
+ | **Duplicate memory** | Near-duplicate memories across projects (>60% content overlap) |
91
+ | **Loop detection** | Agent stuck in loops — repeated commands or cyclic patterns in session history |
92
+
93
+ ## Supported Context Files
94
+
95
+ | File | Tool |
96
+ | ---------------------------------------------------------------------------------------------------- | --------------------------- |
97
+ | `CLAUDE.md`, `CLAUDE.local.md`, `.claude/rules/*.md` | Claude Code |
98
+ | `AGENTS.md`, `AGENT.md`, `AGENTS.override.md` | AAIF / Multi-agent standard |
99
+ | `.cursorrules`, `.cursor/rules/*.md`, `.cursor/rules/*.mdc`, `.cursor/rules/*/RULE.md` | Cursor |
100
+ | `.github/copilot-instructions.md`, `.github/instructions/*.md`, `.github/git-commit-instructions.md` | GitHub Copilot |
101
+ | `.windsurfrules`, `.windsurf/rules/*.md` | Windsurf |
102
+ | `GEMINI.md` | Gemini CLI |
103
+ | `.clinerules` | Cline |
104
+ | `.aiderules` | Aider |
105
+ | `.aide/rules/*.md` | Aide / Codestory |
106
+ | `.amazonq/rules/*.md` | Amazon Q Developer |
107
+ | `.goose/instructions.md`, `.goosehints` | Goose by Block |
108
+ | `.junie/guidelines.md`, `.junie/AGENTS.md` | JetBrains Junie |
109
+ | `.aiassistant/rules/*.md` | JetBrains AI Assistant |
110
+ | `.continuerules`, `.continue/rules/*.md` | Continue |
111
+ | `.rules` | Zed |
112
+ | `replit.md` | Replit |
113
+
114
+ ## MCP Server Config Linting
115
+
116
+ 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.
117
+
118
+ ```bash
119
+ # Lint context files + MCP configs
120
+ npx @yawlabs/ctxlint@latest --mcp
121
+
122
+ # Lint only MCP configs
123
+ npx @yawlabs/ctxlint@latest --mcp-only
124
+
125
+ # Include global/user-level configs (Claude Desktop, Cursor, Windsurf, etc.)
126
+ npx @yawlabs/ctxlint@latest --mcp-global
127
+ ```
128
+
129
+ ### What MCP config files are scanned
130
+
131
+ | File | Client |
132
+ | ----------------------------- | -------------------------------------- |
133
+ | `.mcp.json` | Claude Code (universal project config) |
134
+ | `.cursor/mcp.json` | Cursor |
135
+ | `.vscode/mcp.json` | VS Code / GitHub Copilot |
136
+ | `.amazonq/mcp.json` | Amazon Q Developer |
137
+ | `.continue/mcpServers/*.json` | Continue |
138
+
139
+ With `--mcp-global`, also scans Claude Desktop, Cursor, Windsurf, and Amazon Q global configs.
140
+
141
+ ### What MCP config checks catch
142
+
143
+ | Check | What it finds |
144
+ | --------------- | -------------------------------------------------------------------------------------- |
145
+ | **Schema** | Invalid JSON, wrong root key (`servers` vs `mcpServers`), missing required fields |
146
+ | **Security** | Hardcoded API keys and Bearer tokens in git-tracked config files |
147
+ | **Commands** | Missing `cmd /c` wrapper for npx on Windows, broken file paths in args |
148
+ | **Deprecated** | SSE transport usage (deprecated March 2025, use Streamable HTTP) |
149
+ | **Env vars** | Wrong env var syntax for the client (`${VAR}` vs `${env:VAR}` vs `${{ secrets.VAR }}`) |
150
+ | **URLs** | Malformed URLs, localhost in project configs, missing path component |
151
+ | **Consistency** | Same server configured differently across client configs |
152
+ | **Redundancy** | Disabled servers, identical configs at multiple scopes |
153
+
154
+ ### Example MCP config output
155
+
156
+ ```
157
+ MCP Configs
158
+ .mcp.json
159
+ ✗ mcp-security Server "api": hardcoded Bearer token in a git-tracked file
160
+ ✗ mcp-deprecated Server "old-svc": SSE transport is deprecated — use "http"
161
+ ✓ mcp-schema
162
+ ✓ mcp-commands
163
+ .cursor/mcp.json
164
+ ✗ mcp-env Server "api": Cursor uses ${env:VAR}, not ${VAR}
165
+ ✓ mcp-schema
166
+ .vscode/mcp.json
167
+ ✗ mcp-schema .vscode/mcp.json must use "servers" as root key, not "mcpServers"
168
+
169
+ Cross-file
170
+ ⚠ Server "api" is configured differently in .mcp.json and .cursor/mcp.json
171
+ ℹ Server "db" is in .mcp.json but missing from .cursor/mcp.json
172
+
173
+ Summary: 3 errors, 2 warnings, 1 info
174
+ ```
175
+
176
+ ### MCP Config Linting Specification
177
+
178
+ The full specification for MCP config linting rules, the cross-client config landscape, and a machine-readable rule catalog are published as open specifications:
179
+
180
+ - **[`MCP_CONFIG_LINT_SPEC.md`](./MCP_CONFIG_LINT_SPEC.md)** — the full lint-rule set (rule count in the [Specifications](#specifications) family table), the complete client/format reference, and implementation guidance. Tool-agnostic — any linter can implement it.
181
+ - **[`mcp-config-lint-rules.json`](./mcp-config-lint-rules.json)** — Machine-readable rule catalog for programmatic consumption by AI agents, CI systems, and other tools.
182
+
183
+ ## mcph Config Linting
184
+
185
+ ctxlint also lints `.mcph.json` — the config file read by the [`@yawlabs/mcph`](https://github.com/YawLabs/mcph) CLI. Distinct from `.mcp.json` (different schema, different threat model). Applies across the user-global (`~/.mcph.json`), per-project (`.mcph.json`), and machine-local (`.mcph.local.json`) scope cascade.
186
+
187
+ > **Note:** the mcph rule family (and the `ctxlint_mcph_audit` MCP tool) is **under review** — the upstream mcp.hosting platform is archived, so this family's future is being reassessed. The rules and tool still ship and work; only their long-term status is undecided.
188
+
189
+ ```bash
190
+ # Lint context files + .mcph.json
191
+ npx @yawlabs/ctxlint@latest --mcph
192
+
193
+ # Lint only .mcph.json
194
+ npx @yawlabs/ctxlint@latest --mcph-only
195
+
196
+ # Include the user-global ~/.mcph.json
197
+ npx @yawlabs/ctxlint@latest --mcph-global
198
+
199
+ # Treat any token in any .mcph.json as an error (env-var-only posture)
200
+ npx @yawlabs/ctxlint@latest --mcph --mcph-strict-env-token
201
+ ```
202
+
203
+ ### What mcph config checks catch
204
+
205
+ | Check | What it finds |
206
+ | --------------------------- | ----------------------------------------------------------------------------------------------------------------- |
207
+ | **mcph-token-security** | mcp.hosting PAT (`mcp_pat_*`) leaks, malformed tokens, and prefers env-var (`MCPH_TOKEN`) over file-stored tokens |
208
+ | **mcph-apibase** | Invalid `apiBase` URLs and plaintext HTTP to public hosts (private hosts like `localhost` / RFC 1918 are exempt) |
209
+ | **mcph-schema-conformance** | Unknown / typo'd fields and stale `version` numbers vs the current `mcph.config.v1.json` schema |
210
+ | **mcph-lists** | Conflicts (entries in both `servers` allow-list and `blocked` deny-list) and duplicates within either list |
211
+ | **mcph-gitignore** | `.mcph.local.json` not covered by `.gitignore` — machine-local overrides exist precisely to stay machine-local |
212
+
213
+ ## Session Linting
214
+
215
+ 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.
216
+
217
+ ```bash
218
+ # Lint context files + session data
219
+ npx @yawlabs/ctxlint@latest --session
220
+
221
+ # Lint only session data
222
+ npx @yawlabs/ctxlint@latest --session-only
223
+ ```
224
+
225
+ 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).
226
+
227
+ ### What session files are scanned
228
+
229
+ | Agent | History | Memory |
230
+ | ----------- | ------------------------- | ---------------------------------- |
231
+ | Claude Code | `~/.claude/history.jsonl` | `~/.claude/projects/*/memory/*.md` |
232
+ | Codex CLI | `~/.codex/history.jsonl` | — |
233
+
234
+ ### What session checks catch
235
+
236
+ | Check | What it finds |
237
+ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
238
+ | **Missing secrets** | `gh secret set` ran on 2+ sibling repos but not this one |
239
+ | **Diverged configs** | Shared config files (CI workflows, tsconfig, .prettierrc, etc.) with 20-90% line overlap — enough to be related, different enough to be drifting |
240
+ | **Missing workflows** | GitHub Actions workflows in 2+ siblings but absent from this project |
241
+ | **Stale memory** | Memory entries referencing file paths that no longer exist |
242
+ | **Duplicate memory** | Near-duplicate memory entries across projects (>60% overlap) |
243
+ | **Loop detection** | Agent stuck in a loop — 3+ consecutive identical commands, or cyclic A,B,A,B patterns |
244
+ | **Memory index overflow** | `MEMORY.md` exceeds Claude Code's documented 200-line / 25KB session-load cap, so entries past the cap are invisible to the agent |
245
+
246
+ ### Session Linting Specification
247
+
248
+ - **[`AGENT_SESSION_LINT_SPEC.md`](./AGENT_SESSION_LINT_SPEC.md)** — 8 lint rules, the agent session data landscape across 8 agents, sibling detection strategy, and implementation guidance.
249
+ - **[`agent-session-lint-rules.json`](./agent-session-lint-rules.json)** — Machine-readable rule catalog.
250
+
251
+ ## Example Output
252
+
253
+ ```
254
+ ctxlint v0.9.10
255
+
256
+ Scanning /Users/you/my-app...
257
+
258
+ Found 2 context files (1,847 tokens total)
259
+ CLAUDE.md (1,203 tokens, 42 lines)
260
+ AGENTS.md -> CLAUDE.md (symlink)
261
+
262
+ CLAUDE.md
263
+ ✗ Line 12: src/auth/middleware.ts does not exist
264
+ → Did you mean src/middleware/auth.ts? (renamed 14 days ago)
265
+ ✗ Line 8: "pnpm test" — script "test" not found in package.json
266
+ ⚠ Last updated 47 days ago. src/routes/ has 8 commits since.
267
+ ⚠ testing framework conflict: "Vitest" in CLAUDE.md vs "Jest" in AGENTS.md
268
+ ℹ Line 3: "Express" is in package.json dependencies — agent can infer this
269
+
270
+ Summary: 2 errors, 2 warnings, 1 info
271
+ Token usage: 1,203 tokens per agent session
272
+ Estimated waste: ~55 tokens (redundant content)
273
+ ```
274
+
275
+ ## Options
276
+
277
+ ```
278
+ Usage: ctxlint [options] [path]
279
+
280
+ Arguments:
281
+ path Project directory to scan (default: ".")
282
+
283
+ Options:
284
+ --strict Exit code 1 on any warning or error (for CI)
285
+ --checks <list> Comma-separated checks to run (see below)
286
+ --ignore <list> Comma-separated checks to skip
287
+ --fix Auto-fix broken paths using git history and fuzzy matching
288
+ --fix-dry-run Preview --fix changes without writing
289
+ --yes Skip interactive confirmation prompts (required for --fix in TTY)
290
+ --follow-symlinks Allow --fix to write through symlinks (default: skip)
291
+ --format <fmt> Output format: text, json, or sarif (default: text)
292
+ --tokens Show token breakdown per file
293
+ --verbose Show passing checks too
294
+ --quiet Suppress all output except errors (exit code only)
295
+ --config <path> Path to config file (default: .ctxlintrc in project root)
296
+ --depth <n> Max subdirectory depth to scan (default: 2)
297
+ --mcp Enable MCP config linting alongside context file checks
298
+ --mcp-only Run only MCP config checks, skip context file checks
299
+ --mcp-global Also scan user/global MCP config files (implies --mcp)
300
+ --mcph Enable .mcph.json (mcp.hosting CLI config) linting
301
+ --mcph-only Run only mcph config checks
302
+ --mcph-global Also scan ~/.mcph.json (implies --mcph)
303
+ --mcph-strict-env-token Upgrade mcph-token-security/prefer-env-token from warning to error
304
+ --session Enable session audit checks (cross-project consistency)
305
+ --session-only Run only session checks, skip context and MCP checks
306
+ --mcp-server Start the MCP server (alias: `serve` subcommand)
307
+ --watch Re-lint on context file changes
308
+ -V, --version Output the version number
309
+ -h, --help Display help
310
+
311
+ Commands:
312
+ init Set up a git pre-commit hook
313
+ ```
314
+
315
+ **Available checks:** `paths`, `commands`, `staleness`, `tokens`, `tier-tokens`, `redundancy`, `contradictions`, `frontmatter`, `ci-coverage`, `ci-secrets`, `mcp-schema`, `mcp-security`, `mcp-commands`, `mcp-deprecated`, `mcp-env`, `mcp-urls`, `mcp-consistency`, `mcp-redundancy`, `mcph-token-security`, `mcph-apibase`, `mcph-schema-conformance`, `mcph-lists`, `mcph-gitignore`, `session-missing-secret`, `session-diverged-file`, `session-missing-workflow`, `session-stale-memory`, `session-duplicate-memory`, `session-loop-detection`, `session-memory-index-overflow`
316
+
317
+ Passing any `mcp-*` check name implies `--mcp`. Passing any `mcph-*` check name implies `--mcph`. Passing any `session-*` check name implies `--session`.
318
+
319
+ ## Watch Mode
320
+
321
+ ```bash
322
+ npx @yawlabs/ctxlint@latest --watch
323
+ ```
324
+
325
+ Re-lints automatically when any context file, MCP config, or `package.json` changes. Useful during development when you're editing context files alongside code.
326
+
327
+ ## Use in CI
328
+
329
+ ```yaml
330
+ - name: Lint context files
331
+ run: npx @yawlabs/ctxlint@latest --strict
332
+ ```
333
+
334
+ ### Exit Codes
335
+
336
+ | Code | Meaning |
337
+ | ---- | -------------------------------------------------------------------- |
338
+ | `0` | Success — no issues, or issues below the strict threshold |
339
+ | `1` | Strict mode caught at least one error or warning (`--strict` is set) |
340
+ | `2` | Config error, invalid CLI option, or internal failure |
341
+
342
+ In non-strict mode ctxlint always exits `0` — it's a reporting tool by default. Pass `--strict` to enforce in CI.
343
+
344
+ ### GitHub Action
345
+
346
+ ```yaml
347
+ - name: Lint context files
348
+ uses: yawlabs/ctxlint-action@v1
349
+ ```
350
+
351
+ Or with options:
352
+
353
+ ```yaml
354
+ - name: Lint context files
355
+ uses: yawlabs/ctxlint-action@v1
356
+ with:
357
+ args: '--strict --mcp'
358
+ ```
359
+
360
+ ### SARIF Output (GitHub Code Scanning)
361
+
362
+ ```yaml
363
+ - name: Lint context files
364
+ run: npx @yawlabs/ctxlint@latest --format sarif > ctxlint.sarif
365
+
366
+ - name: Upload SARIF
367
+ uses: github/codeql-action/upload-sarif@v3
368
+ with:
369
+ sarif_file: ctxlint.sarif
370
+ ```
371
+
372
+ ## Auto-fix
373
+
374
+ ```bash
375
+ npx @yawlabs/ctxlint@latest --fix
376
+ ```
377
+
378
+ When a broken path was renamed in git or has a close match in the project, `--fix` rewrites the context file automatically.
379
+
380
+ ## Pre-commit Hook
381
+
382
+ ### Built-in
383
+
384
+ ```bash
385
+ npx @yawlabs/ctxlint@latest init
386
+ ```
387
+
388
+ Sets up a git pre-commit hook that runs `ctxlint --strict` before each commit.
389
+
390
+ ### pre-commit framework
391
+
392
+ Add to your `.pre-commit-config.yaml`:
393
+
394
+ ```yaml
395
+ repos:
396
+ - repo: https://github.com/yawlabs/ctxlint
397
+ rev: v0.9.10
398
+ hooks:
399
+ - id: ctxlint
400
+ ```
401
+
402
+ ## Config File
403
+
404
+ Create a `.ctxlintrc` or `.ctxlintrc.json` in your project root:
405
+
406
+ ```json
407
+ {
408
+ "checks": ["paths", "commands", "tokens", "contradictions", "frontmatter"],
409
+ "ignore": ["redundancy"],
410
+ "strict": true,
411
+ "tokenThresholds": {
412
+ "info": 500,
413
+ "warning": 2000,
414
+ "error": 5000,
415
+ "aggregate": 4000,
416
+ "tierBreakdown": 1000,
417
+ "tierAggregate": 4000
418
+ },
419
+ "contextFiles": ["CONVENTIONS.md", "docs/ai-rules.md"]
420
+ }
421
+ ```
422
+
423
+ The `contextFiles` array adds custom file patterns to scan alongside the built-in list. Useful for project-specific context files like `CONVENTIONS.md`.
424
+
425
+ ### Config Reference
426
+
427
+ | Field | Type | Default | Meaning |
428
+ | ------------------------------- | ---------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
429
+ | `checks` | `string[]` | all checks | Checks to run. Check names include `paths`, `commands`, `tokens`, `tier-tokens`, `redundancy`, `contradictions`, `frontmatter`, `staleness`, `ci-coverage`, `ci-secrets`, plus any `mcp-*` / `session-*`. |
430
+ | `ignore` | `string[]` | `[]` | Checks to skip, evaluated after `checks`. |
431
+ | `strict` | `boolean` | `false` | Exit non-zero on any warning or error. |
432
+ | `tokenThresholds` | `object` | see below | Per-file and cross-file token thresholds. |
433
+ | `tokenThresholds.info` | `number` | `1000` | Per-file info threshold for `tokens/info`. |
434
+ | `tokenThresholds.warning` | `number` | `3000` | Per-file warning threshold for `tokens/large`. |
435
+ | `tokenThresholds.error` | `number` | `8000` | Per-file error threshold for `tokens/excessive`. |
436
+ | `tokenThresholds.aggregate` | `number` | `5000` | Cross-file total threshold for `tokens/aggregate`. |
437
+ | `tokenThresholds.tierBreakdown` | `number` | `1000` | Always-loaded file threshold for `tier-tokens/section-breakdown`. |
438
+ | `tokenThresholds.tierAggregate` | `number` | `4000` | Combined always-loaded threshold for `tier-tokens/aggregate`. |
439
+ | `contextFiles` | `string[]` | `[]` | Extra glob patterns to scan alongside the built-in list. |
440
+ | `mcp` | `boolean` | `false` | Enable MCP config checks by default (same as `--mcp`). |
441
+ | `mcpOnly` | `boolean` | `false` | Run only MCP config checks, skip context-file checks (same as `--mcp-only`). |
442
+ | `mcpGlobal` | `boolean` | `false` | Also scan user/global MCP configs (same as `--mcp-global`). |
443
+ | `mcph` | `boolean` | `false` | Enable `.mcph.json` (mcp.hosting CLI config) checks (same as `--mcph`). |
444
+ | `mcphOnly` | `boolean` | `false` | Run only mcph config checks, skip context-file checks (same as `--mcph-only`). |
445
+ | `mcphGlobal` | `boolean` | `false` | Also scan `~/.mcph.json` user-global config (same as `--mcph-global`). |
446
+ | `mcphStrictEnvToken` | `boolean` | `false` | Upgrade `mcph-token-security/prefer-env-token` from warning to error (same as `--mcph-strict-env-token`). |
447
+ | `session` | `boolean` | `false` | Enable session audit checks (cross-project consistency); same as `--session`. |
448
+ | `sessionOnly` | `boolean` | `false` | Run only session checks, skip context and MCP checks (same as `--session-only`). |
449
+
450
+ Config file resolution order: `.ctxlintrc` → `.ctxlintrc.json` in the project root. Use `--config <path>` to point elsewhere. CLI flags override config fields.
451
+
452
+ CLI flags override config file settings. Use `--config <path>` to load a config from a custom location.
453
+
454
+ ## Use as MCP Server
455
+
456
+ ctxlint ships with an MCP server that exposes seven tools (`ctxlint_audit`, `ctxlint_mcp_audit`, `ctxlint_mcph_audit`, `ctxlint_session_audit`, `ctxlint_validate_path`, `ctxlint_token_report`, `ctxlint_fix`). All read-only tools declare annotations so MCP clients can skip confirmation dialogs.
457
+
458
+ Launch it with the `serve` subcommand (or the equivalent `--mcp-server` flag, kept for back-compat):
459
+
460
+ ```bash
461
+ npx -y @yawlabs/ctxlint@latest serve
462
+ ```
463
+
464
+ ### With Claude Code
465
+
466
+ ```bash
467
+ claude mcp add ctxlint -- npx -y @yawlabs/ctxlint@latest serve
468
+ ```
469
+
470
+ ### With `.mcp.json` (Claude Code project config, Cursor, Windsurf)
471
+
472
+ Create `.mcp.json` in your project root:
473
+
474
+ macOS / Linux / WSL:
475
+
476
+ ```json
477
+ {
478
+ "mcpServers": {
479
+ "ctxlint": {
480
+ "command": "npx",
481
+ "args": ["-y", "@yawlabs/ctxlint@latest", "serve"]
482
+ }
483
+ }
484
+ }
485
+ ```
486
+
487
+ Windows:
488
+
489
+ ```json
490
+ {
491
+ "mcpServers": {
492
+ "ctxlint": {
493
+ "command": "cmd",
494
+ "args": ["/c", "npx", "-y", "@yawlabs/ctxlint@latest", "serve"]
495
+ }
496
+ }
497
+ }
498
+ ```
499
+
500
+ > **Tip:** This file is safe to commit — it contains no secrets.
501
+
502
+ ### With VS Code / GitHub Copilot
503
+
504
+ Add to `.vscode/mcp.json`:
505
+
506
+ ```json
507
+ {
508
+ "servers": {
509
+ "ctxlint": {
510
+ "command": "npx",
511
+ "args": ["-y", "@yawlabs/ctxlint@latest", "serve"]
512
+ }
513
+ }
514
+ }
515
+ ```
516
+
517
+ ### With Claude Desktop
518
+
519
+ Add to your Claude Desktop config (`claude_desktop_config.json`):
520
+
521
+ ```json
522
+ {
523
+ "mcpServers": {
524
+ "ctxlint": {
525
+ "command": "npx",
526
+ "args": ["-y", "@yawlabs/ctxlint@latest", "serve"]
527
+ }
528
+ }
529
+ }
530
+ ```
531
+
532
+ ## JSON Output
533
+
534
+ ```bash
535
+ npx @yawlabs/ctxlint@latest --format json
536
+ ```
537
+
538
+ Returns structured JSON with all file results, issues, and summary — useful for building integrations or dashboards.
539
+
540
+ ## Specifications
541
+
542
+ 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.
543
+
544
+ | Spec | What it covers |
545
+ | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
546
+ | **[AI Context File Linting Spec](./CONTEXT_LINT_SPEC.md)** | 28 rules for validating context files (CLAUDE.md, .cursorrules, AGENTS.md, etc.) across 17 clients. Covers file formats, frontmatter schemas, path/command validation, staleness, token budgets, redundancy, and contradictions. |
547
+ | **[MCP Config Linting Spec](./MCP_CONFIG_LINT_SPEC.md)** | 27 rules for validating MCP server configs (.mcp.json, .cursor/mcp.json, .vscode/mcp.json, etc.) across 8 clients. Covers schema validation, hardcoded secrets, env var syntax, deprecated transports, and cross-file consistency. |
548
+ | **mcph Config Linting** (`mcph-config-lint-rules.json`) | 10 rules for validating `.mcph.json` — the config file read by the `@yawlabs/mcph` CLI. Covers PAT format + leakage, env-var posture, plaintext API endpoints, schema drift, and allow/deny list semantics across the scope cascade. |
549
+ | **[Agent Session Linting Spec](./AGENT_SESSION_LINT_SPEC.md)** | 8 rules for auditing agent session data (history, memory) across 8 agents. Covers cross-project secret consistency, config drift, stale memory, and loop detection. |
550
+ | **[Agent Skill Linting Spec](./AGENT_SKILL_LINT_SPEC.md)** | 5 rules for auditing Claude Code skill (`SKILL.md`) and agent (`.md`) definitions under `~/.claude`. Covers frontmatter presence, broken refs, trigger-phrase collisions, orphaned skills, and dead tool restrictions. (v1, experimental) |
551
+
552
+ All specs include machine-readable rule catalogs for programmatic consumption:
553
+
554
+ - [`context-lint-rules.json`](./context-lint-rules.json) — context file rules and 16 supported format definitions
555
+ - [`mcp-config-lint-rules.json`](./mcp-config-lint-rules.json) — MCP config rules and 8 client definitions
556
+ - [`mcph-config-lint-rules.json`](./mcph-config-lint-rules.json) — mcph CLI config rules (`.mcph.json`)
557
+ - [`agent-session-lint-rules.json`](./agent-session-lint-rules.json) — session lint rules and 8 agent data source definitions
558
+ - [`agent-skill-lint-rules.json`](./agent-skill-lint-rules.json) — agent-skill lint rules (`~/.claude/skills`, `~/.claude/agents`)
559
+
560
+ ## Also By Yaw Labs
561
+
562
+ - [Yaw](https://yaw.sh) — The AI-native terminal
563
+ - [Spend](https://spend.sh) — AI spend tracking, cost estimation, and provider comparison across 10+ providers
564
+ - [Token Limit News](https://tokenlimit.news) — Weekly AI dev tooling newsletter
565
+
566
+ ## License
567
+
568
+ MIT