dorkian-context-lint 0.1.1

uvx --from git+https://github.com/dorkian/contextlint contextlint

_{No API key. No network. No telemetry. No dependencies.}

_{Install · Install via AI assistant · Usage · Scheduled health checks · Dashboard · Reproducing the numbers · How it compares · Privacy}

The problem in one chart

Every skill, instruction file and MCP tool schema your assistant loads is injected into the system prompt before your first message. You pay for it on every request, including the ones where none of it is relevant.

Existing tools price a skill by its size on disk. But a well-formed skill's body only loads when it is invoked — what you pay every turn is its one-line catalog entry. Conflate the two and you are wrong by an order of magnitude, in the direction that flatters the savings claim.

contextlint separates the two, prices them independently, and refuses to add together numbers that mean different things.

What it looks like

--html report.html writes a self-contained visual report: a treemap of always-on cost coloured by whether you have ever invoked the asset, a cost-against-usage scatter, and filterable findings. One file, no CDN, works offline, respects your system theme.

Live Dashboard

A local React + Vite dashboard over the same data, for when running it or screen-sharing it beats reading a terminal.

The overview tells the whole story before any scrolling: the always-on total against your context window, a diagram of why it splits the way it does — drawn live from the current report, not illustrated once — and the safe-to-reclaim / worth-reviewing split, kept apart the same way the CLI keeps them apart. Below that: always-on cost by asset as a ranked, square-root-scaled column chart; cost against real usage; findings you can filter, search and click through to a file path; and an Apply Fixes flow that mirrors the CLI's own git-dirty-tree guard rather than silently bypassing it with --allow-dirty.

cd dashboard
npm install
npm run dev

Open http://localhost:3535. Point it at any project by clicking the path in the header, or load ?path=/absolute/path/to/project directly — bookmarkable, or embeddable behind a fixed link. The server binds to 127.0.0.1 only and never builds a shell command from a string (execFile with an argument array throughout) — the exact class of exposure this tool exists to flag, closed in the one place here that could have had it.

Install

Not on PyPI yet — install from the repository. Python 3.10+, zero required dependencies.

# run it once, install nothing
uvx --from git+https://github.com/dorkian/contextlint contextlint

# or put `contextlint` on your PATH
uv tool install git+https://github.com/dorkian/contextlint
pipx install git+https://github.com/dorkian/contextlint
pip install git+https://github.com/dorkian/contextlint

Two optional extras, neither needed for the default path:

uv tool install "dorkian-context-lint[exact] @ git+https://github.com/dorkian/contextlint"  # tiktoken, measured counts
uv tool install "dorkian-context-lint[api] @ git+https://github.com/dorkian/contextlint"    # anthropic, for --tokenizer anthropic

The distribution name is dorkian-context-lint — PyPI's namespace-similarity check rejects the shorter contextlint. The installed command is unaffected: it's still contextlint, matching everything above.

uv tool upgrade contextlint      # or: uv tool install --force git+https://...

git clone https://github.com/dorkian/contextlint && cd contextlint
pip install -e ".[dev]"
python -m pytest tests -q

Install via your AI assistant

Zero required dependencies and a single git URL means there is nothing for an assistant to get wrong. Paste this into Claude Code, Cursor, Copilot, Codex CLI, or anything else with terminal access:

Install the contextlint CLI from https://github.com/dorkian/contextlint. It is not
published to PyPI yet, so do not run a bare `pip install contextlint` — it will 404.
Install directly from git instead: use `uv tool install
git+https://github.com/dorkian/contextlint` if uv is available, otherwise `pipx install
git+https://github.com/dorkian/contextlint`, otherwise `pip install --user
git+https://github.com/dorkian/contextlint`. Then run `contextlint --version` to confirm
it worked, and `contextlint audit --no-global` in this project to show me a real report.

Also install this as a Claude Code skill: run `mkdir -p ~/.claude/skills/contextlint &&
curl -fsSL
https://raw.githubusercontent.com/dorkian/contextlint/main/skill/contextlint/SKILL.md -o
~/.claude/skills/contextlint/SKILL.md`. Then, in future sessions, I can just ask about my
context budget, dead skills, or MCP security and you'll know to reach for contextlint.

Three things nothing else does

1. It reads your session history

Static analysis tells you a skill is large. Only the transcripts tell you that you have never once used it. Those two facts lead to opposite actions.

Nothing leaves your machine — only tool-invocation names and timestamps are parsed, never prompt or response text.

2. It treats MCP security as a first-class check

Unauthenticated remote servers · plaintext HTTP · credentials in env, in headers, and in argv · unpinned npx -y supply chains · shell-launched servers · filesystem servers rooted at / · blanket permission rules · and instruction-shaped text hidden in tool descriptions, including zero-width and Unicode-tag characters that render as nothing to you and as text to the model.

It also measures what a server actually costs, which configuration alone cannot tell you:

3. It separates what is certain from what is a judgement call

Deleting a byte-identical duplicate cannot change behaviour. Deleting a skill you have not invoked in 90 days might.

Usage

contextlint                            # audit this project + your global config
contextlint --html report.html         # visual report
contextlint --format json              # machine-readable
contextlint --assistant cursor         # one assistant only
contextlint --no-global                # this project only
contextlint --tokenizer tiktoken       # exact counts
contextlint --fail-on high             # exit 1 in CI when something serious is found
contextlint --mcp-probe                # measure real MCP tool schemas (starts your servers)
contextlint checks                     # list adapters and checks
contextlint fix                        # print a plan; changes nothing
contextlint fix --apply                # apply it, with a backup and an undo
contextlint restore <backup-dir>       # undo a fix run, on any platform

contextlint watch --every 6h           # keep checking, and report what changed
contextlint watch --once --quiet       # one check with drift — the form for cron

Keeping it healthy over time

Agent config rots the way dependencies rot: nobody adds 4,000 tokens on purpose, it arrives 200 at a time. watch re-runs the audit and reports drift rather than the same numbers again.

$ contextlint watch --every 6h
2026-09-07T08:42:31+00:00  ·  OK    ·  always-on 18,703 (9.4%)  ·  +412 since last  ·  new 1  ·  findings 96
      + MCP server '#' publishes # tools costing # tokens every turn

Each run appends a small snapshot to .contextlint-history.jsonl — aggregates and finding fingerprints, never asset content. Fingerprints strip numbers out of titles, so a server going from 26 to 27 tools is not reported as one finding resolved and another appearing.

--once is the form to put in cron, systemd, launchd or a scheduled CI job: something else owns the scheduling, and contextlint still knows what the numbers were yesterday. --quiet prints nothing while healthy, so cron only mails you when it is not. Exit code is 0 for ok and warn, 1 for fail.

Ready-made snippets for cron, launchd, systemd, GitHub Actions and pre-commit are in docs/scheduling.md. This repository runs the check on itself in .github/workflows/context-health.yml.

Reproducing the numbers

Every figure in this README has a command attached. That is the point.

python benchmarks/run.py                                              # detection + savings
uv run --no-project --with tiktoken python benchmarks/calibrate.py    # tokenizer error
uv run --no-project --with tiktoken python benchmarks/tune.py         # refit the heuristic

The 14% is small on purpose. It is what an automatic, behaviour-preserving fix actually recovers. The larger number — the assets you have never invoked — is reported separately and left to you, because deleting them is a decision, not an optimisation.

How it compares

Verified against the GitHub API, not taken from anyone's README.

The two niches are each crowded; the intersection was empty. gh search repos "context window audit agent skills" returns zero results.

Privacy

The default path reads local files, makes no network connection, and writes nothing. Asset content never appears in the JSON or HTML output — only names, paths and counts.

Two modes are exceptions, both opt-in and both announced at the point of use: --mcp-probe starts your configured servers, and --tokenizer anthropic sends configuration text to the Anthropic API. See SECURITY.md.

Design notes

• One adapter per assistant, one file per check. Adding an assistant is one file and one registry entry.
• No required dependencies. A tool whose thesis is that dependencies have a cost should demonstrate that it believes it.
• Findings are signals, not verdicts. Every security finding names the pattern it matched and why, so you can dismiss it in ten seconds when it is wrong.
• Never claim a percentage the harness cannot reproduce.
• Charts are generated, not drawn. docs/assets/make_charts.py builds every graphic above from measured JSON, and CI fails if a committed chart no longer matches its data.

Full contract in SPEC.md. The dogfood audit is written up in docs/case-study.md.

Related work

Four Claude Code token optimizers exist — valorisa/Claude-Skills, Sharan0516/claude-token-optimizer, 4pixeltechBR/token_saver_ClaudeCode, KINGSTAR-OMEGA/claude-token-optimizer — alongside a separate cluster of MCP security scanners. contextlint sits in the gap between them. Sharan0516's router pattern — replacing always-loaded descriptions with a lightweight catalog — is the strongest idea in the existing field and directly informed how loading modes are modelled here.

Licence

MIT