contextlint github →
§ HERO / 000

markdownlint for syntax. contextlint for meaning.

Your AI writes the docs. contextlint verifies them — deterministically. A semantic linter for structured Markdown that catches broken cross-references, missing sections, and dependency drift across your editor, your AI assistants, and your CI.

get started github
[rules]
21
[categories]
07
[protocols]
3
LSP · MCP · CLI
[latency]
<1s
§ 001
// THE PROBLEM

The doc graph is too big to lint by eye.

A modern spec-driven repo can have hundreds of Markdown files referencing each other. When your AI adds another one — or rewrites three at once — humans can't track what just broke.

[obs:001]

Reviewers nod.
CI passes.
The drift compounds.

§ 002
// THE APPROACH

Generation is creative.
Verification should not be.

Use AI to write your docs — that's where it shines. Use contextlint to verify them. Static analysis catches what's checkable; AI focuses on what's actually generative. The separation keeps your CI deterministic and your reviews fast.

  • [p.1] Same input, same result — no prompts, no temperature.
  • [p.2] Cross-file aware — knows your dependency graph.
  • [p.3] 21 rules across 7 categories.
  • [p.4] Sub-second on a typical repo. Built for CI.
§ 003
// CHECKPOINTS

One linter,
three checkpoints.

contextlint plugs into the entire document lifecycle — from your editor to your AI assistant to your CI gate.

[ckpt.01]
while you write

editor diagnostics

See errors as you type. Hover for context. Quick-fix common violations with one click.

  • → VS Code
  • → Cursor
  • → Neovim
  • → Helix
  • → JetBrains
[ckpt.02]
while AI writes

AI agent integration

Your AI calls contextlint to verify its own output before handing it back to you.

  • → Claude Code
  • → Cursor Agent
  • → Cline
  • → Windsurf
[ckpt.03]
before merge

CI enforcement

The last gate. Block PRs with broken cross-references or missing sections.

  • → GitHub Actions
  • → npm scripts
  • → pre-commit

[ref:proto] Built on Model Context Protocol (MCP) and Language Server Protocol (LSP). Works with any compatible client.

§ 004
// INSPECTION

Six examples.
Twenty-one rules.

A glimpse of what contextlint catches. The full set spans tables, sections, structure, references, checklists, content quality, and dependency graphs.

[TBL-002] table

Empty cells

| ID     | Description |
|--------|-------------|
| FR-101 | User login  |
| FR-102 |             |
[err]
Required cell at FR-102 / Description is empty.
[SEC-001] section

Missing required section

# ADR-005: Database choice

## Context
We need persistent storage.

## Decision
Use PostgreSQL.
[err]
Required section 'Consequences' is missing.
[REF-001] reference

Broken cross-reference

## Login spec

See [FR-102](./req.md#fr-102) for the
full requirement and test cases.
[err]
ID 'FR-102' is not defined in req.md.
[CHK-001] checklist

Incomplete checklist

## Acceptance criteria

- [x] User can log in
- [ ] Session persists across reloads
- [ ] Logout clears all tokens
[err]
2 unchecked items remain in 'Acceptance criteria'.
[CTX-001] context

Placeholder still present

## Non-functional

- Performance target: TBD
- Owner: TODO
- Review date: <pending>
[err]
Placeholders 'TBD', 'TODO', '<pending>' detected.
[GRP-002] graph

Circular reference

architecture.md  →  api-design.md
api-design.md    →  data-model.md
data-model.md    →  architecture.md
[err]
Circular dependency: architecture → api-design → data-model → architecture.

// see the full ruleset →

§ 005
// QUICK START

From zero to first lint
in two commands.

[step.01] // install
npm install -D @contextlint/cli

// or: bunx, pnpm, yarn

[step.02] // lint
npx contextlint "**/*.md"

// add a config file to enable cross-file rules

[config] // contextlint.config.json
{
  "$schema": "https://raw.githubusercontent.com/nozomi-koborinai/contextlint/main/schema.json",
  "include": ["docs/**/*.md", "specs/**/*.md"],
  "rules": [
    { "rule": "ref001" },
    { "rule": "sec001", "options": { "sections": ["Context", "Decision", "Consequences"] } },
    { "rule": "grp002" }
  ]
}

Then plug into your editor for live diagnostics, or run as a CI gate. See the README for the full configuration reference.

§ 006
// INTEGRATIONS

Plugs into the
tools you already use.

One core engine, three protocols. No editor lock-in, no AI vendor lock-in.

editors

[via LSP]
  • → VS Code
  • → Cursor
  • → Neovim
  • → Helix
  • → JetBrains
  • → VSCodium
  • → Windsurf

AI assistants

[via MCP]
  • → Claude Code
  • → Cursor Agent
  • → Cline
  • → Windsurf

continuous integration

[as CLI]
  • → GitHub Actions
  • → npm scripts
  • → pre-commit
  • → Husky
  • → lint-staged
§ 007
// ORIGIN

Built from lived practice.

[testimony:001]

"I practice spec-driven development at work. Maintaining consistency across hundreds of Markdown files is a real problem — broken cross-references and duplicate IDs go undetected. So I built contextlint to solve it."

Nozomi Koborinai
Author · koborin.ai

contextlint is open source. Contributions, rule proposals, and bug reports are welcome on GitHub.