trueline-mcp 2.6.2 → 2.7.0

package/INSTALL.md

@@ -148,6 +148,44 @@ to use trueline tools instead of `read_file` and `shell cat`.
 Codex CLI does not support hooks. The instruction file is the only mechanism
 for tool redirection (~60% compliance).
 
+## CLI (no MCP)
+
+For agents that can run shell commands but don't support MCP, trueline
+provides a standalone CLI with the same hash-verified operations.
+
+### 1. Install
+
+```sh
+npm i -g trueline-mcp
+```
+
+This puts the `trueline` command on your PATH.
+
+### 2. Verify
+
+```sh
+trueline --help
+```
+
+### 3. Configure your agent
+
+Add the contents of `configs/cli/instructions.md` to your agent's system
+prompt or instruction file. This teaches the agent the trueline workflow:
+outline, read targeted ranges, search for edit targets, edit with checksums.
+
+The key rules for the agent:
+
+- Use `trueline read` instead of `cat`
+- Use `trueline edit` instead of `sed` or manual file writes
+- Use `trueline outline` to navigate before reading full files
+- Use `trueline search` to find lines with checksums before editing
+
+### 4. Path access
+
+By default the CLI allows access to the current working directory. Set
+`TRUELINE_ALLOWED_DIRS` to a colon-separated list of additional paths,
+or set `CLAUDE_PROJECT_DIR` to override the project root.
+
 ## CLI hook dispatcher
 
 The `trueline-hook` command is the universal entry point for hook integration:

package/README.md

@@ -2,9 +2,9 @@
 
 [![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)
 
-A [Model Context Protocol](https://modelcontextprotocol.io/) plugin that reduces
-context usage on large files and catches editing mistakes. Works with Claude
-Code, Gemini CLI, VS Code Copilot, OpenCode, and Codex CLI.
+An [MCP](https://modelcontextprotocol.io/) plugin that gives AI coding agents
+hash-verified file editing and targeted reads. Works with Claude Code, Gemini
+CLI, VS Code Copilot, OpenCode, and Codex CLI.
 
 ## Installation
 
@@ -16,38 +16,35 @@ Code, Gemini CLI, VS Code Copilot, OpenCode, and Codex CLI.
 ```
 
 **Other platforms** (Gemini CLI, VS Code Copilot, OpenCode, Codex CLI):
-See [INSTALL.md](INSTALL.md) for platform-specific setup instructions.
+See [INSTALL.md](INSTALL.md) for platform-specific setup.
 
-## The problem
+**CLI (no MCP):** For agents that use shell commands instead of MCP, install
+globally with `npm i -g trueline-mcp` and add `configs/cli/instructions.md`
+to your agent's system prompt. See [INSTALL.md](INSTALL.md#cli-no-mcp).
 
-AI agents waste tokens on large files in two ways:
+## Why
 
-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.
+AI coding agents read entire files to find one function, then echo back
+everything they're replacing. Both waste context on content the agent already
+knows or doesn't need. That context costs money, eats into the conversation
+window, and limits how much real work fits in a session.
 
-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.
+Worse, the built-in edit tools match by string content. If the agent
+hallucinates a line, works from stale context, or hits an ambiguous match,
+your code gets silently corrupted.
 
-Both problems compound on larger files. A typical editing session reads
-dozens of files and makes multiple edits, burning through context on
-redundant content.
+trueline fixes both problems: it reads less, writes less, and rejects every
+edit that doesn't match the file's actual content.
 
-And when things go wrong (stale reads, hallucinated anchors, ambiguous
-matches) the agent silently corrupts your code.
+## How it works
 
-## How trueline fixes this
+trueline provides six MCP tools organized around three workflows.
 
-trueline provides six MCP tools that are smaller, faster, and verified.
-For small files, the built-in tools work fine. For larger files, the
-savings from targeted reads and compact edits outweigh the token
-overhead of crossing the MCP protocol barrier.
+### Explore: understand before you read
 
-### 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:
+`trueline_outline` returns an AST-based structural outline of any file:
+functions, classes, declarations, and their line ranges. For a typical
+source file, that's 10-20 lines instead of hundreds.
 
 ```
 1-10: (10 imports)
@@ -60,64 +57,78 @@ classes, and declarations with their line ranges:
 (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.
+The agent sees the full structure, then uses `trueline_read` to fetch only
+the ranges it needs. A 500-line file where the agent needs one 20-line
+function? It reads 20 lines, not 500.
 
-The savings scale with file size. MCP tool calls have per-call framing
-overhead, so the break-even point is roughly 15KB; below that, a plain
-`Read` is cheaper. Above it, the gap widens quickly:
+`trueline_search` finds lines by literal string or regex and returns them
+with edit-ready checksums, no outline or read step needed. For targeted
+edits where the agent knows what it's looking for, this is the fastest path.
 
-| File size   | Full read | Outline | Savings |
-|-------------|-----------|---------|--------|
-| 140 lines   | 140 tokens | 12 tokens | 91% |
-| 245 lines   | 245 tokens | 14 tokens | 94% |
-| 504 lines   | 504 tokens | 4 tokens  | 99% |
+### Edit: compact and verified
 
-`trueline_read` supports multiple disjoint ranges in a single call.
+The built-in edit tool requires the agent to echo back the old text being
+replaced. `trueline_edit` replaces that with a compact line-range reference
+and a content hash. The agent outputs only the new content.
 
-### Find and fix: `trueline_search`
+The savings scale with the size of the replaced block. A one-line change
+saves little; replacing 30 lines of old code saves the agent from
+outputting all 30 of those lines again.
 
-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.
+Multiple edits can be batched in a single call and applied atomically.
 
-A search-based workflow uses **~127 tokens** vs **~2000** for
-outline+read, a 93% reduction for targeted lookups.
+### Review: semantic diffs
 
-### Write less: `trueline_edit`
+`trueline_diff` provides an 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. Pass `["*"]` to diff all changed files at once.
 
-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.
+### Hash verification: no silent corruption
 
-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.
+Every line from `trueline_read` and `trueline_search` carries a content
+hash. Every edit must present those hashes back, proving the agent is
+editing what it thinks it's editing.
 
-Multiple edits can be batched in a single call and applied atomically.
+If the file changed since the agent read it (concurrent edits, a build
+step, another tool), the edit is rejected. If the agent hallucinates
+content that doesn't match what's on disk, the edit is rejected. If the
+agent targets the wrong lines, the edit is rejected. Nothing hits disk
+unless the hashes match.
+
+`trueline_verify` checks whether held checksums are still valid without
+re-reading the file. When nothing changed (the common case), the response
+is a single line.
+
+## How agents actually use it
 
-### Review smarter: `trueline_diff`
+trueline doesn't just register tools and hope the agent picks them up.
+On platforms that support hooks, it actively intercepts the agent's
+workflow:
 
-`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.
+- **SessionStart** injects instructions telling the agent how and when
+  to use each trueline tool, calibrated per platform.
+- **PreToolUse** intercepts calls to the built-in edit tool and blocks
+  them, forcing the agent through hash-verified edits instead.
 
-Pass `["*"]` to diff all changed files at once. The output is compact
-enough to review an entire feature branch in a single tool call.
+With hooks, agent compliance is ~98%. Without hooks (instruction-only
+platforms like OpenCode and Codex CLI), compliance is ~60%. The
+instruction file still helps; hooks make it reliable.
 
-### Never corrupt: hash verification
+The instructions are not one-size-fits-all. They reference each
+platform's native tool names (`Read`/`Edit` on Claude Code,
+`read_file`/`edit_file` on Gemini CLI, `view`/`edit` on OpenCode) and
+adapt advice accordingly.
 
-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.
+## Where it helps most
 
-No more silent corruption. No more ambiguous string matches.
+trueline's overhead is an MCP round-trip per tool call. For small files
+(under ~200 lines), the built-in tools are perfectly fine, and the
+injected instructions tell the agent so.
 
-`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.
+The payoff comes on larger files and multi-file editing sessions, where
+targeted reads and compact edits avoid sending hundreds or thousands of
+redundant lines through the context window.
 
 ## Design
 

package/bin/trueline.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+// CLI entry point for npm distribution.
+// Delegates to resolve-binary-cli.cjs which prefers bun > deno > node.
+//
+// Usage:
+//   npx trueline read src/foo.ts
+//   trueline read src/foo.ts        # after npm i -g trueline-mcp
+
+import { execFileSync } from "node:child_process";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const script = resolve(__dirname, "..", "scripts", "resolve-binary-cli.cjs");
+
+try {
+  execFileSync("node", [script, ...process.argv.slice(2)], { stdio: "inherit" });
+} catch (err) {
+  process.exit(err.status ?? 1);
+}

package/configs/cli/instructions.md

@@ -0,0 +1,74 @@
+# trueline CLI
+
+trueline provides hash-verified file operations via the command line.
+Use trueline commands instead of cat, grep, and sed for reading and
+editing files. Edits are verified against checksums to prevent stale
+overwrites.
+
+## Commands
+
+- **trueline read** — Read a file with per-line hashes and range checksums.
+- **trueline edit** — Apply hash-verified edits. Each edit needs a checksum from a prior read or search.
+- **trueline outline** — Compact structural outline (functions, classes, types with line ranges).
+- **trueline search** — Search a file for a string or regex. Returns matching lines with hashes, ready for editing.
+- **trueline diff** — Semantic AST-based diff vs a git ref.
+- **trueline verify** — Check if held checksums are still valid.
+
+Run `trueline --help` or `trueline <command> --help` for full usage.
+
+## Workflow
+
+1. **Navigate:** `trueline outline src/foo.ts` to see structure without reading the full file.
+2. **Read targeted ranges:** `trueline read src/foo.ts --ranges 10-25` to read only what you need.
+3. **Find edit targets:** `trueline search src/foo.ts "oldFunction"` to get lines with checksums.
+4. **Edit with verification:** `trueline edit src/foo.ts --edits '[{"checksum":"...","range":"...","content":"..."}]'`
+5. **Preview first (optional):** Add `--dry-run` to see a unified diff without writing.
+
+## Rules
+
+- Never use `cat` to read files; use `trueline read` instead.
+- Never use `sed` or manual file writes; use `trueline edit` instead.
+- Use `trueline outline` for navigation; only read specific ranges you need.
+- Always pass the checksum from `trueline read` or `trueline search` when editing.
+- If an edit fails with a checksum mismatch, re-read the file to get fresh checksums.
+
+## Edit format
+
+The `--edits` flag takes a JSON array. Each edit object has:
+
+- `checksum` — Range checksum from a prior read (format: `startLine-endLine:hexhash`)
+- `range` — Target lines, in one of three formats:
+  - `startLine:lineHash-endLine:lineHash` — replace lines
+  - `+lineNum:hash` — insert after line
+  - `+0:` — insert at beginning of file
+- `content` — New content for those lines
+
+Example:
+
+```sh
+trueline edit src/foo.ts --edits '[{
+  "checksum": "10-15:a1b2c3d4",
+  "range": "10:ab-15:cd",
+  "content": "function newName() {\n  return true;\n}"
+}]'
+```
+
+To insert after a line (without replacing), use `+lineNum:hash` as the range:
+
+```sh
+trueline edit src/foo.ts --edits '[{
+  "checksum": "10-15:a1b2c3d4",
+  "range": "+12:ef",
+  "content": "// inserted after line 12"
+}]'
+```
+
+To insert at the beginning of a file, use `+0:` as the range:
+
+```sh
+trueline edit src/foo.ts --edits '[{
+  "checksum": "1-1:a1b2c3d4",
+  "range": "+0:",
+  "content": "// Copyright 2025 Acme Corp\n// SPDX-License-Identifier: MIT\n"
+}]'
+```