Skip to content
/

ctxlint

ctxlint · YawLabs/ctxlint · ★ 6 · last commit 2026-05-24

Primitive shape 7 total
MCP tools 7
00

Summary

ctxlint — Summary

ctxlint is a TypeScript/npm linter that validates AI agent context files (CLAUDE.md, .cursorrules, AGENTS.md, .mcp.json, etc.) against the actual codebase they describe, catching broken paths, stale commands, contradictions, and secret leaks before the agent encounters them. It ships as both a CLI binary (ctxlint) and an MCP server with 7 tools, supports 17+ AI coding clients (Claude Code, Cursor, Copilot, Windsurf, Gemini, Cline, Aider, and more), and provides auto-fix via --fix for broken path references using git history. The intervention point is pre-session static linting: ctxlint runs before the agent does, ensuring context files are truthful. It also provides watch mode (--watch) and session-quality analysis (stale memory entries, loop detection). Compared to seeds: ctxlint is spec-kit's closest functional analog — both lint agent context files and integrate with CI — but ctxlint is substantially broader (16 AI tools, MCP server mode, auto-fix, cross-project consistency checks) and targets the file quality problem rather than spec-driven workflow enforcement.

01

Overview

ctxlint — Overview

Origin

Repo: YawLabs/ctxlint (github.com/YawLabs/ctxlint). Created April 2026, published to npm as @yawlabs/ctxlint v0.12.1. Organization: Yaw Labs. TypeScript, MIT license. 6 stars.

Philosophy

From the README:

"Your CLAUDE.md is lying to your agent. Your .mcp.json has a hardcoded API key. ctxlint catches both."

The core insight: context files are the single most important interface between developer and agent, yet they degrade as the codebase evolves. ctxlint applies traditional linting discipline to that interface. The README frames the problem:

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

Design Principles

  • Zero runtime dependencies — ships as a single self-contained ~400KB bundle; npx downloads and starts immediately
  • Cross-tool — deliberately multi-client (16+ AI tools) rather than Claude-only
  • Auto-fix--fix uses git rename history to suggest and apply path corrections
  • Token-aware — shows how much context window each file consumes, flags redundant content
  • MCP server mode — 7 tools for IDE/agent integration with tool annotations for auto-approval

Spec Published as Open Standard

YawLabs also publishes the lint spec itself as open documents:

  • CONTEXT_LINT_SPEC.md — 21 rules in 9 categories for context files
  • MCP_CONFIG_LINT_SPEC.md — linting rules for .mcp.json and related config
  • AGENT_SESSION_LINT_SPEC.md — session quality rules These are published as CC BY 4.0 open standards any linter can implement.
02

Architecture

ctxlint — Architecture

Distribution

  • npm package: @yawlabs/ctxlint
  • CLI binary: ctxlint (defined in package.json#bin)
  • MCP server: npx @yawlabs/ctxlint serve
  • Pre-commit hook: via .pre-commit-hooks.yaml (hooks.yaml published)
  • GitHub Action: action.yml in repo root
  • CI step: installable as dev dependency

Install Methods

npx -y @yawlabs/ctxlint@latest          # zero-install
npm install -D @yawlabs/ctxlint         # project dev dep
npm install -g @yawlabs/ctxlint         # global

Directory Structure (repo)

ctxlint/
  src/
    cli.ts               CLI entry point
    core/
      checks/            Individual lint check implementations
      audit.ts           Audit logic
      scanner.ts         File scanning
      parser.ts          Context file parsing
      session-parser.ts  Session data parsing
      reporter.ts        Output formatting
      fixer.ts           Auto-fix logic
      config.ts          Configuration loading
    mcp/                 MCP server tools
    utils/
  fixtures/              Test fixtures
  tests/
  .claude/
    settings.local.json
  .pre-commit-hooks.yaml
  action.yml
  context-lint-rules.json     Machine-readable rule catalog
  mcp-config-lint-rules.json  MCP config rules
  agent-session-lint-rules.json Session rules
  CONTEXT_LINT_SPEC.md
  MCP_CONFIG_LINT_SPEC.md
  AGENT_SESSION_LINT_SPEC.md
  server.json              MCP server manifest

Required Runtime

  • Node.js (exact version: unknown from public readme, but bundled as single file)

Target AI Tools

Claude Code, Cursor, GitHub Copilot, Windsurf, Gemini CLI, Cline, Aider, and 9+ more (16 AI tools total according to README).

Config Files Read

File Purpose
CLAUDE.md, CLAUDE.local.md, .claude/rules/*.md Claude Code context
AGENTS.md, AGENT.md Multi-agent standard
.cursorrules, `.cursor/rules/*.md .mdc`
.github/copilot-instructions.md Copilot
.windsurfrules, .windsurf/rules/*.md Windsurf
.mcp.json MCP server config (secret scanning)
03

Components

ctxlint — Components

CLI Binary: ctxlint

Single binary, primary flags:

Flag Purpose
--strict Treat warnings as errors
--fix Auto-rewrite broken path references using git rename history
--watch Watch mode — re-lints when context files change
--json Output as JSON
--sarif Output as SARIF (GitHub Code Scanning compatible)

MCP Server: 7 Tools

Served via npx @yawlabs/ctxlint serve:

Tool Purpose
lint-context-files Lint context files in a project
lint-mcp-config Lint .mcp.json and related configs
audit-session Audit a Claude Code session for quality signals
fix-path Auto-fix a specific broken path reference
list-rules List all available lint rules
check-cross-project Check config consistency across sibling projects
suggest-coverage Suggest missing CI workflow documentation

(Tool names from README description of "7 tools for IDE/agent integration with tool annotations for auto-approval")

Lint Rules (21 rules, 9 categories)

Category Rules
paths Broken paths, git rename detection
commands Wrong build/test commands vs package.json
staleness Context not updated after code changes
tokens Context window budget, redundant content
redundancy Content agent can already infer
contradictions Conflicting directives across files
frontmatter Invalid YAML frontmatter for Cursor/Copilot/Windsurf
ci-coverage CI workflows not documented in context
ci-secrets Secrets in CI not mentioned in context

Session/Memory Rules

Additional rules in agent-session-lint-rules.json:

Rule Purpose
Stale memory Claude Code memory entries with nonexistent paths
Duplicate memory Near-duplicate entries (>60% overlap)
Loop detection Repeated commands or cyclic patterns
Cross-project secrets GitHub secrets missing from sibling projects
Diverged configs Canonical configs drifting across siblings

Pre-commit Hook

Published .pre-commit-hooks.yaml for integration with pre-commit framework.

GitHub Action

action.yml for direct GitHub Actions integration.

Hooks (Claude Code)

None — ctxlint does NOT ship Claude Code hooks. It relies on external invocation (CI, pre-commit, MCP) rather than Claude lifecycle hooks.

05

Prompts

ctxlint — Prompts

ctxlint ships no LLM prompt files. Its checks are deterministic code, not LLM calls. However, it publishes three open lint specification documents that serve as the conceptual "prompts" for implementing the checks.

Verbatim Excerpt 1: CONTEXT_LINT_SPEC.md (opening framing)

# AI Context File Linting Specification

**Version:** 1.0.0-draft
**Date:** 2026-04-07
**Maintained by:** Yaw Labs / ctxlint
**License:** CC BY 4.0

## What is this?

AI coding agents are guided by context files — markdown documents like `CLAUDE.md`, 
`.cursorrules`, and `AGENTS.md` that tell the agent how a project works. These files 
reference source paths, build commands, frameworks, and conventions. When the code 
changes and the context files don't, the agent follows stale instructions and fails.

This specification defines a standard set of lint rules for validating AI agent context 
files across all major AI coding clients. It is tool-agnostic: any linter, IDE extension, 
CI check, or AI agent can implement these rules.

Technique: Open specification pattern — ctxlint publishes the rule definitions as a CC BY 4.0 standard so other tools can implement the same rules, creating ecosystem network effects.

Verbatim Excerpt 2: README check table

| 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            |
| **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) |
| **Stale memory**      | Claude Code memory entries referencing paths that no longer exist                             |
| **Loop detection**    | Agent stuck in loops — repeated commands or cyclic patterns in session history                |

Technique: exhaustive enumeration — the README provides a complete, flat table of all checks, making the tool's scope instantly scannable. This is a documentation-as-specification pattern.

Design Note

ctxlint deliberately does not use LLMs for any checks. From the spec: checks are deterministic code — path existence, regex matching against package.json scripts, git log parsing for rename detection. This is a conscious design choice: zero LLM calls means zero latency, zero cost, and 100% deterministic results.

09

Uniqueness

ctxlint — Uniqueness & Positioning

Differs from Seeds

ctxlint is closest to spec-kit among the 11 seeds: both validate AI context files and can run in CI pipelines. However, the architectural delta is significant. spec-kit uses 18 Claude Code lifecycle hooks (PreToolUse/PostToolUse) to enforce behavior during sessions, and its "linting" is really about enforcing a spec-driven workflow. ctxlint is a pure pre-session static linter with zero hooks — it runs before the agent starts and catches factual errors in context files (broken paths, stale commands, hardcoded secrets). ctxlint is also substantially broader: it targets 16+ AI tools vs spec-kit's primary focus on Claude Code/Copilot. The auto-fix feature (using git rename history) has no analog in any seed framework. The MCP server mode makes ctxlint uniquely callable by agents themselves — an agent can lint its own context mid-session.

Positioning

Signal type: static lint (pre-session context validation) Intervention point: before sessions start (or mid-session via MCP) Target user: any team using AI coding tools, CI pipelines, pre-commit hooks Unique features: auto-fix with git rename history, cross-project consistency, SARIF output, open CC BY 4.0 spec standard, 16+ AI tool support, loop detection

Observable Failure Modes

  • Deterministic checks can't catch semantic drift (context claims "we use hexagonal architecture" — valid statement, but wrong after a refactor)
  • Cross-project checks require access to sibling repos (not always available in CI)
  • Token-waste heuristics may flag legitimate context as redundant
  • v0.12.1 is young — rule coverage for non-Claude tools may lag

Relationship to Other Batch 31 Frameworks

ctxlint is the most tool-agnostic and pre-session-focused framework in this batch. It is the only framework here that publishes its check rules as an open CC BY 4.0 specification for other tools to implement. Sponsio, DashClaw, and clauder all intervene during agent execution; ctxlint catches problems before execution starts.

04

Workflow

ctxlint — Workflow

Phases

Phase Description Artifact
File discovery Scan project for all context files (16+ patterns) File list
Static parsing Parse context files, extract path/command references AST/token list
Codebase cross-reference Validate paths, commands against actual project Finding list
Session analysis Parse ~/.claude session data (if enabled) Session metrics
Report Output findings as text, JSON, or SARIF Report
Fix (optional) Rewrite broken paths using git rename history Updated files

Typical Developer Workflow

# 1. Instant static check (team use, CI)
npx -y @yawlabs/ctxlint@latest --strict

# 2. With auto-fix
npx -y @yawlabs/ctxlint@latest --fix

# 3. Watch mode during active development
npx -y @yawlabs/ctxlint@latest --watch

# 4. CI JSON output
npx -y @yawlabs/ctxlint@latest --json

Approval Gates

None for linting. The --fix flag modifies files but uses git rename history to validate suggestions — no interactive gate.

CI Integration Pattern

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

MCP Server Workflow

When running as MCP server, IDE/agent calls tools directly:

  1. lint-context-files — returns finding list
  2. fix-path — applies fix for specific finding
  3. Agent addresses findings inline before coding session proceeds

Execution Mode

  • CLI: one-shot (per invocation) or watch (daemon while files change)
  • MCP: event-driven (responds to tool calls)
06

Memory Context

ctxlint — Memory & Context

State Storage

ctxlint itself has no persistent state. Each invocation is stateless.

Data Sources Read

Source Purpose
Project context files (CLAUDE.md, .cursorrules, etc.) Primary lint targets
package.json, Makefile Command cross-reference
.mcp.json Secret scanning, config validation
~/.claude/ (optional) Session quality analysis (stale memory, loops)
.github/workflows/ CI coverage and secret audit
Sibling project directories Cross-project consistency checks
git log Rename detection for auto-fix

Watch Mode State

In --watch mode, ctxlint monitors context files for changes using file system events and re-runs affected checks. This is in-process ephemeral state (no persistence).

MCP Server State

When running as MCP server (npx @yawlabs/ctxlint serve), server process holds parsed rule definitions in memory. Stateless between tool calls.

Cross-Session Analysis

The session-quality rules (stale memory, duplicate memory, loop detection) read Claude Code's session store at ~/.claude/ but do not write anything back to it.

Compaction

Not applicable.

07

Orchestration

ctxlint — Orchestration

Multi-Agent

No. ctxlint is a single-process linter. No agent coordination.

Orchestration Pattern

None.

Isolation Mechanism

None. Single process reads filesystem.

Execution Modes

Mode Trigger Description
one-shot npx ctxlint Run checks, print report, exit
watch npx ctxlint --watch File-system monitor; re-lint on change
MCP server npx ctxlint serve Event-driven; respond to tool calls

Multi-Model

No. Zero LLM calls.

Cross-Tool Portability

High — ctxlint targets 16+ AI tools. Unlike vibelint (Claude Code-only) or pi-steering-hooks (pi-agent-only), ctxlint reads context files for Claude Code, Cursor, Copilot, Windsurf, Gemini CLI, Cline, Aider, and others.

Consensus

None.

Prompt Chaining

Not applicable (no LLM usage).

08

Ui Cli Surface

ctxlint — UI & CLI Surface

CLI Binary

Exists: yes Name: ctxlint Package: @yawlabs/ctxlint v0.12.1 Is thin wrapper: no — own runtime Install: npx -y @yawlabs/ctxlint@latest or npm install -D @yawlabs/ctxlint

Local UI

None. Terminal output only.

Output Modes

Mode Trigger Format
Terminal report default ANSI-colored text
JSON --json Structured findings
SARIF --sarif GitHub Code Scanning format

MCP Server

Exists: yes Install: npx @yawlabs/ctxlint serve Tools: 7 tools Protocol: stdio Tool annotations: auto-approval annotations for safe read-only tools

MCP server exposes lint functionality to IDE agents and other MCP clients. Example config for Claude Code:

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

GitHub Action

action.yml in repo root — directly usable as uses: YawLabs/ctxlint@main.

Pre-commit Integration

.pre-commit-hooks.yaml published for pre-commit framework integration.

mcp.hosting Integration

One-click installation button published for mcp.hosting platform (syncs to all MCP clients).

IDE Integration

Via MCP server — any IDE with MCP client support can call ctxlint tools directly.

Related frameworks

same archetype · same primary tool · same memory type

Taskmaster AI ★ 27k

Converts a PRD into a dependency-ordered JSON task graph that AI coding agents execute one task at a time, eliminating context…

ccmemory ★ 1

Accumulates decisions, corrections, and failed approaches from Claude Code sessions into a queryable Neo4j graph so each new…

Pimzino spec-workflow-mcp ★ 4.2k

MCP server providing spec-driven development workflow with dashboard-backed approval gates, implementation logging, and VSCode…

MCP Shrimp Task Manager ★ 2.1k

Convert natural language requests into structured AI development tasks with chain-of-thought enforcement, reflection gates, and…

Bernstein ★ 460

Govern parallel CLI coding agents with a deterministic Python scheduler, HMAC-chained audit trail, and compliance-ready signed…

LeanSpec ★ 252

Provides a unified spec CLI and MCP server over any existing spec backend (markdown, GitHub Issues, ADO), making spec-driven…