trueline-mcp
An MCP plugin that gives AI coding agentshash-verified file editing and targeted reads. Works with Claude Code, GeminiCLI, 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.
CLI (no MCP): For agents that use shell commands instead of MCP, installglobally with npm i -g trueline-mcp and add configs/cli/instructions.mdto your agent's system prompt. See INSTALL.md.
Why
AI coding agents read entire files to find one function, then echo backeverything they're replacing. Both waste context on content the agent alreadyknows or doesn't need. That context costs money, eats into the conversationwindow, and limits how much real work fits in a session.
Worse, the built-in edit tools match by string content. If the agenthallucinates a line, works from stale context, or hits an ambiguous match,your code gets silently corrupted.
trueline fixes both problems: it reads less, writes less, and rejects everyedit that doesn't match the file's actual content.
How it works
trueline provides six MCP tools organized around three workflows.
Explore: understand before you read
trueline_outline returns an AST-based structural outline of any file:functions, classes, declarations, and their line ranges. For a typicalsource file, that's 10-20 lines instead of hundreds.
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)
The agent sees the full structure, then uses trueline_read to fetch onlythe ranges it needs. Ranges are specified inline on each path:
file_paths: ["src/server.ts:25-45", "src/utils.ts:1-10,80-90"]
A 500-line file where the agent needs one 20-line function? It reads 20lines, not 500. Multiple files with different ranges in a single call.
trueline_search finds lines by literal string or regex and returns themwith edit-ready refs, no outline or read step needed. For targetededits where the agent knows what it's looking for, this is the fastest path.
Edit: compact and verified
The built-in edit tool requires the agent to echo back the old text beingreplaced. trueline_edit replaces that with a compact line-range referenceand a content hash. The agent outputs only the new content.
The savings scale with the size of the replaced block. A one-line changesaves little; replacing 30 lines of old code saves the agent fromoutputting all 30 of those lines again.
Multiple edits can be batched in a single call and applied atomically.
Review: semantic diffs
trueline_changes provides an AST-based summary of structural changescompared to a git ref. Instead of raw line diffs, it reportsadded/removed/renamed symbols, signature changes, and logic modificationswith inline mini-diffs. Pass ["*"] to diff all changed files at once.
Hash verification: no silent corruption
Every line from trueline_read and trueline_search carries a contenthash. Every edit must present those hashes back, proving the agent isediting what it thinks it's editing.
If the file changed since the agent read it (concurrent edits, a buildstep, another tool), the edit is rejected. If the agent hallucinatescontent that doesn't match what's on disk, the edit is rejected. If theagent targets the wrong lines, the edit is rejected. Nothing hits diskunless the hashes match.
trueline_verify checks whether held refs are still valid withoutre-reading the file. When nothing changed (the common case), the responseis a single line.
How agents actually use it
trueline doesn't just register tools and hope the agent picks them up.On platforms that support hooks, it actively intercepts the agent'sworkflow:
- SessionStart injects instructions telling the agent how and whento use each trueline tool, calibrated per platform.
- PreToolUse intercepts calls to the built-in read and edit tools,redirecting reads of files over 3 KB to trueline and blockingunverified edits entirely.
- Shipped skill (
skills/trueline-workflow/SKILL.md) auto-discoverson any file-editing prompt, carrying richer examples and workflowguidance for clients that honor Claude Code skills.
With hooks, agent compliance is ~98%. Without hooks (instruction-onlyplatforms like OpenCode and Codex CLI), compliance is ~60%. Theinstruction file still helps; hooks make it reliable.
The instructions are not one-size-fits-all. They reference eachplatform's native tool names (Read/Edit on Claude Code,read_file/edit_file on Gemini CLI, view/edit on OpenCode) andadapt advice accordingly.
Where it helps most
trueline's overhead is an MCP round-trip per tool call. For small files(under ~3 KB), the built-in tools are perfectly fine and pass throughwithout interception.
The payoff comes on larger files and multi-file editing sessions, wheretargeted reads and compact edits avoid sending hundreds or thousands ofredundant lines through the context window.
In a typical 20-turn session exploring 8 files and editing 3, truelinesaves roughly 11,000 tokens of mid-session context plus 623 tokens perturn from leaner instructions, for an estimated $1.58 per session inreduced API cost.
Design
See DESIGN.md for the protocol specification, hashalgorithm 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
Security model
trueline-mcp assumes a single-user filesystem trust model: the invoking useris trusted, and any process running as that user can already read and writethe same files trueline can.
validatePath() blocks path traversal and symlink escape at check time byresolving with realpath() and verifying containment within the projectdirectory, TRUELINE_ALLOWED_DIRS, and (under Claude Code) ~/.claude/.
Concurrent symlink races (TOCTOU) — where another process under the sameUID swaps a directory component between the check and a later open — are notin scope. Closing them would require fd-based I/O throughout the codebase,which conflicts with the streaming and atomic-rename design. That tradeoff isstated here rather than left implicit.
As defense-in-depth, read-side opens of user-supplied paths pass O_NOFOLLOWon POSIX. A leaf-component symlink swap between validatePath and the openfails the open rather than silently following. Writes and rename targets areunchanged — the edit path's temp-file and rename pattern was alreadysymlink-safe.
If you run trueline in a shared-account or multi-tenant environment, hardenthe OS layer (chroot, mount namespaces) rather than relying on trueline'spath checks alone.
Inspiration
Inspired by The Harness Problemby Can Boluk and thevscode-hashline-edit-toolby Seth Livingston.
