trueline-mcp

A Model Context Protocol plugin that cuts context usage and catches editing mistakes. Works with Claude Code, Gemini CLI, VS Code Copilot, OpenCode, and Codex CLI.

Installation

Claude Code (recommended; hooks are automatic):

/plugin marketplace add rjkaes/trueline-mcp
/plugin install trueline-mcp@trueline-mcp

Other platforms (Gemini CLI, VS Code Copilot, OpenCode, Codex CLI): See INSTALL.md for platform-specific setup instructions.

The problem

AI agents waste tokens in two ways:

1. Reading too much. To find a function in a 500-line file, the agent reads all 500 lines, most of which it doesn't need.

2. Echoing on edit. The built-in Edit tool requires the agent to output the old text being replaced (old_string) plus the new text. The old text is pure overhead.

Both problems compound. A typical editing session reads dozens of files and makes multiple edits, burning through context on redundant content.

And when things go wrong (stale reads, hallucinated anchors, ambiguous matches) the agent silently corrupts your code.

How trueline fixes this

trueline replaces the built-in Read and Edit with six tools that are smaller, faster, and verified.

Read less: trueline_outline + trueline_read

Instead of reading an entire file, the agent starts with trueline_outline, a compact AST outline showing just the functions, classes, and declarations with their line ranges:

1-10: (10 imports)
12-12: const VERSION = pkg.version;
14-17: const server = new McpServer({
25-45: async function resolveAllowedDirs(): Promise<string[]> {
49-69: server.registerTool(
71-92: server.registerTool(

(12 symbols, 139 source lines)

12 lines instead of 139. The agent sees the full structure, then reads only the ranges it needs, skipping hundreds of irrelevant lines.

trueline_read supports multiple disjoint ranges in a single call and an optional hashes: false mode for exploratory reads that saves ~3 tokens per line.

Find and fix: trueline_search

When the agent knows what it's looking for, trueline_search finds lines by regex and returns them with enough context to edit immediately, no outline or read step needed.

A search-based workflow uses ~127 tokens vs ~2000 for outline+read, a 93% reduction for targeted lookups.

Write less: trueline_edit

The built-in Edit makes the model echo back the old text being replaced. trueline_edit replaces that with a compact line-range reference: the model only outputs the new content.

For a typical 15-line edit, that's 44% fewer output tokens. Output tokens are the most expensive token class, so this adds up fast.

Multiple edits can be batched in a single call and applied atomically.

Review smarter: trueline_diff

trueline_diff provides a semantic, AST-based summary of structural changes compared to a git ref. Instead of raw line diffs, it reports added/removed/renamed symbols, signature changes, and logic modifications with inline mini-diffs for small changes.

Pass ["*"] to diff all changed files at once. The output is compact enough to review an entire feature branch in a single tool call.

Never corrupt: hash verification

Every line from trueline_read carries a content hash. Every edit must present those hashes back, proving the agent is working against the file's actual content. If anything changed (concurrent edits, model hallucination, stale context) the edit is rejected before any bytes hit disk.

No more silent corruption. No more ambiguous string matches.

trueline_verify lets the agent check whether held checksums are still valid without re-reading the file. When the file hasn't changed (the common case), the response is a single line — near-zero tokens.

Benchmarks

Measured on real project files (src/streaming-edit.ts, 529 lines), comparing total bytes through the context window (call + result, ÷4 ≈ tokens):

The search-and-fix workflow saves the most: a single trueline_search call replaces grep + full-file read + old-string echo, cutting 96% of token usage. The verify-before-edit workflow shows how trueline_verify avoids a full re-read when checking whether held checksums are still valid — 92% savings over re-reading the entire file. Even the explore-then-edit workflow — which includes an exploratory read, a targeted re-read, and an edit — still saves 63% over the built-in equivalent.

Run the benchmark yourself: bun run benchmarks/token-benchmark.ts

Design

See DESIGN.md for the protocol specification, hash algorithm details, streaming architecture, and security model.

Development

Requires Bun ≥ 1.3.

bun install          # install dependencies
bun test             # run tests
bun run build        # build binary for the current platform

Inspiration

Inspired by The Harness Problem by Can Boluk and the vscode-hashline-edit-tool by Seth Livingston.

Special Thanks