{"id":46343964,"url":"https://github.com/rjkaes/trueline-mcp","last_synced_at":"2026-04-12T01:06:26.900Z","repository":{"id":342064302,"uuid":"1172669784","full_name":"rjkaes/trueline-mcp","owner":"rjkaes","description":"Smarter reads, safer edits. An MCP plugin that cuts token usage and catches editing mistakes before they hit disk. Supports Claude Code, Gemini CLI, GitHub Copilot, and Codex.","archived":false,"fork":false,"pushed_at":"2026-03-31T18:20:26.000Z","size":2195,"stargazers_count":12,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-31T19:43:36.279Z","etag":null,"topics":["agentic-coding","ai-coding","anthropic","ast","claude-code","developer-tools","gemini-cli","github-copilot","llm","mcp","mcp-server","model-context-protocol","multi-agent","openai-codex","token-optimization","tree-sitter","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rjkaes.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-04T15:12:31.000Z","updated_at":"2026-03-31T18:20:30.000Z","dependencies_parsed_at":"2026-03-11T02:00:54.769Z","dependency_job_id":null,"html_url":"https://github.com/rjkaes/trueline-mcp","commit_stats":null,"previous_names":["rjkaes/trueline-mcp"],"tags_count":45,"template":false,"template_full_name":null,"purl":"pkg:github/rjkaes/trueline-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rjkaes%2Ftrueline-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rjkaes%2Ftrueline-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rjkaes%2Ftrueline-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rjkaes%2Ftrueline-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rjkaes","download_url":"https://codeload.github.com/rjkaes/trueline-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rjkaes%2Ftrueline-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31291003,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-coding","ai-coding","anthropic","ast","claude-code","developer-tools","gemini-cli","github-copilot","llm","mcp","mcp-server","model-context-protocol","multi-agent","openai-codex","token-optimization","tree-sitter","typescript"],"created_at":"2026-03-04T21:03:13.322Z","updated_at":"2026-04-12T01:06:26.888Z","avatar_url":"https://github.com/rjkaes.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# trueline-mcp\n\n[![CI](https://github.com/rjkaes/trueline-mcp/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/rjkaes/trueline-mcp/actions/workflows/ci.yml)\n\nAn [MCP](https://modelcontextprotocol.io/) plugin that gives AI coding agents\nhash-verified file editing and targeted reads. Works with Claude Code, Gemini\nCLI, VS Code Copilot, OpenCode, and Codex CLI.\n\n## Installation\n\n**Claude Code** (recommended; hooks are automatic):\n\n```\n/plugin marketplace add rjkaes/trueline-mcp\n/plugin install trueline-mcp@trueline-mcp\n```\n\n**Other platforms** (Gemini CLI, VS Code Copilot, OpenCode, Codex CLI):\nSee [INSTALL.md](INSTALL.md) for platform-specific setup.\n\n**CLI (no MCP):** For agents that use shell commands instead of MCP, install\nglobally with `npm i -g trueline-mcp` and add `configs/cli/instructions.md`\nto your agent's system prompt. See [INSTALL.md](INSTALL.md#cli-no-mcp).\n\n## Why\n\nAI coding agents read entire files to find one function, then echo back\neverything they're replacing. Both waste context on content the agent already\nknows or doesn't need. That context costs money, eats into the conversation\nwindow, and limits how much real work fits in a session.\n\nWorse, the built-in edit tools match by string content. If the agent\nhallucinates a line, works from stale context, or hits an ambiguous match,\nyour code gets silently corrupted.\n\ntrueline fixes both problems: it reads less, writes less, and rejects every\nedit that doesn't match the file's actual content.\n\n## How it works\n\ntrueline provides six MCP tools organized around three workflows.\n\n### Explore: understand before you read\n\n`trueline_outline` returns an AST-based structural outline of any file:\nfunctions, classes, declarations, and their line ranges. For a typical\nsource file, that's 10-20 lines instead of hundreds.\n\n```\n1-10: (10 imports)\n12-12: const VERSION = pkg.version;\n14-17: const server = new McpServer({\n25-45: async function resolveAllowedDirs(): Promise\u003cstring[]\u003e {\n49-69: server.registerTool(\n71-92: server.registerTool(\n\n(12 symbols, 139 source lines)\n```\n\nThe agent sees the full structure, then uses `trueline_read` to fetch only\nthe ranges it needs. Ranges are specified inline on each path:\n\n```\nfile_paths: [\"src/server.ts:25-45\", \"src/utils.ts:1-10,80-90\"]\n```\n\nA 500-line file where the agent needs one 20-line function? It reads 20\nlines, not 500. Multiple files with different ranges in a single call.\n\n`trueline_search` finds lines by literal string or regex and returns them\nwith edit-ready refs, no outline or read step needed. For targeted\nedits where the agent knows what it's looking for, this is the fastest path.\n\n### Edit: compact and verified\n\nThe built-in edit tool requires the agent to echo back the old text being\nreplaced. `trueline_edit` replaces that with a compact line-range reference\nand a content hash. The agent outputs only the new content.\n\nThe savings scale with the size of the replaced block. A one-line change\nsaves little; replacing 30 lines of old code saves the agent from\noutputting all 30 of those lines again.\n\nMultiple edits can be batched in a single call and applied atomically.\n\n### Review: semantic diffs\n\n`trueline_changes` provides an AST-based summary of structural changes\ncompared to a git ref. Instead of raw line diffs, it reports\nadded/removed/renamed symbols, signature changes, and logic modifications\nwith inline mini-diffs. Pass `[\"*\"]` to diff all changed files at once.\n\n### Hash verification: no silent corruption\n\nEvery line from `trueline_read` and `trueline_search` carries a content\nhash. Every edit must present those hashes back, proving the agent is\nediting what it thinks it's editing.\n\nIf the file changed since the agent read it (concurrent edits, a build\nstep, another tool), the edit is rejected. If the agent hallucinates\ncontent that doesn't match what's on disk, the edit is rejected. If the\nagent targets the wrong lines, the edit is rejected. Nothing hits disk\nunless the hashes match.\n\n`trueline_verify` checks whether held refs are still valid without\nre-reading the file. When nothing changed (the common case), the response\nis a single line.\n\n## How agents actually use it\n\ntrueline doesn't just register tools and hope the agent picks them up.\nOn platforms that support hooks, it actively intercepts the agent's\nworkflow:\n\n- **SessionStart** injects instructions telling the agent how and when\n  to use each trueline tool, calibrated per platform.\n- **PreToolUse** intercepts calls to the built-in read and edit tools,\n  redirecting reads of files over 3 KB to trueline and blocking\n  unverified edits entirely.\n\nWith hooks, agent compliance is ~98%. Without hooks (instruction-only\nplatforms like OpenCode and Codex CLI), compliance is ~60%. The\ninstruction file still helps; hooks make it reliable.\n\nThe instructions are not one-size-fits-all. They reference each\nplatform's native tool names (`Read`/`Edit` on Claude Code,\n`read_file`/`edit_file` on Gemini CLI, `view`/`edit` on OpenCode) and\nadapt advice accordingly.\n\n## Where it helps most\n\ntrueline's overhead is an MCP round-trip per tool call. For small files\n(under ~3 KB), the built-in tools are perfectly fine and pass through\nwithout interception.\n\nThe payoff comes on larger files and multi-file editing sessions, where\ntargeted reads and compact edits avoid sending hundreds or thousands of\nredundant lines through the context window.\n\nIn a typical 20-turn session exploring 8 files and editing 3, trueline\nsaves roughly 11,000 tokens of mid-session context plus 623 tokens per\nturn from leaner instructions, for an estimated $1.58 per session in\nreduced API cost.\n\n## Design\n\nSee [DESIGN.md](DESIGN.md) for the protocol specification, hash\nalgorithm details, streaming architecture, and security model.\n\n## Development\n\nRequires [Bun](https://bun.sh) ≥ 1.3.\n\n```sh\nbun install          # install dependencies\nbun test             # run tests\nbun run build        # build binary for the current platform\n```\n\n## Inspiration\n\nInspired by [The Harness Problem](https://blog.can.ac/2026/02/12/the-harness-problem/)\nby Can Boluk and the\n[vscode-hashline-edit-tool](https://github.com/sethml/vscode-hashline-edit-tool)\nby Seth Livingston.\n\n## Special Thanks\n\n\u003ca href=\"https://github.com/domis86\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/2327600?v=4\" width=\"32\"\u003e\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frjkaes%2Ftrueline-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frjkaes%2Ftrueline-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frjkaes%2Ftrueline-mcp/lists"}