ctxlint

# ctxlint

[![npm version](https://img.shields.io/npm/v/@yawlabs/ctxlint)](https://www.npmjs.com/package/@yawlabs/ctxlint)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![GitHub stars](https://img.shields.io/github/stars/YawLabs/ctxlint)](https://github.com/YawLabs/ctxlint/stargazers)
[![MCP Compliance](https://raw.githubusercontent.com/YawLabs/ctxlint/main/compliance-badge.svg)](https://github.com/YawLabs/mcp-compliance)

**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.

[![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)

One click adds this to your local Yaw MCP config so it's available in every Yaw Terminal session. Or install manually below.

## 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):

```bash
npx -y @yawlabs/ctxlint@latest
```

### Project install (recommended for teams)

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

Then add to your `package.json` scripts:

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

### Global install

```bash
npm install -g @yawlabs/ctxlint
```

Useful if you want `ctxlint` available in every project without per-project setup.

## What It Checks

| Check                    | What it finds                                                                                                                                                                                                                                                                    |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Broken paths**         | File references in context that don't exist in your project                                                                                                                                                                                                                      |
| **Wrong commands**       | Build/test commands that don't match your package.json scripts or Makefile targets, and Gradle project paths or Maven `-pl` modules your build doesn't declare                                                                                                                   |
| **Stale context**        | Context files not updated after recent code changes                                                                                                                                                                                                                              |
| **Token waste**          | How much context window your files consume per session                                                                                                                                                                                                                           |
| **Redundancy**           | Content the agent can already infer (e.g. "We use React" when react is in package.json)                                                                                                                                                                                          |
| **Contradictions**       | Conflicting directives across context files (e.g. "use Jest" in one, "use Vitest" in another)                                                                                                                                                                                    |
| **Frontmatter**          | Invalid or missing YAML frontmatter in Cursor .mdc, Copilot instructions, and Windsurf rules                                                                                                                                                                                     |
| **CI coverage**          | Release/deploy workflows in `.github/workflows/` not documented in any context file                                                                                                                                                                                              |
| **CI secrets**           | Secrets used in CI workflows (`${{ secrets.X }}`) not mentioned in context files                                                                                                                                                                                                 |
| **Inline secrets**       | Real secrets pasted into context files — private-key headers, AWS/GitHub/Anthropic/OpenAI/npm/Slack/Google/Stripe token shapes. Messages never echo the secret (6-char redacted prefix only)                                                                                     |
| **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` |
| **Missing secrets**      | GitHub secrets set on sibling repos but missing from current project                                                                                                                                                                                                             |
| **Diverged configs**     | Canonical config files (CI, tsconfig, etc.) drifting across sibling projects                                                                                                                                                                                                     |
| **Missing workflows**    | GitHub Actions workflows present in 2+ siblings but absent here                                                                                                                                                                                                                  |
| **Stale memory**         | Claude Code memory entries referencing paths that no longer exist                                                                                                                                                                                                                |
| **Duplicate memory**     | Near-duplicate memories across projects (>60% content overlap)                                                                                                                                                                                                                   |
| **Loop detection**       | Agent stuck in loops — repeated commands or cyclic patterns in session history                                                                                                                                                                                                   |
| **Memory overflow**      | `MEMORY.md` past Claude Code's 200-line / 25KB session-load cap — entries beyond it are invisible to the agent                                                                                                                                                                   |
| **Shared temp path**     | A fixed temp path (e.g. `/tmp/pkg.bak`) the agent writes and later reads back — any concurrent session can overwrite it in between                                                                                                                                               |
| **Unverified gate**      |