trueline-workflow

Trueline Workflow

Trueline MCP tools replace built-in Read/Edit/Grep with hash-verified, streaming, ref-based equivalents. Catches hallucinated edits, cuts tokens. Use in right order.

Tool cheat sheet

Tool	Use when	Why
trueline_outline	First look, any file	~10-20 lines vs hundreds
trueline_search	Know target string/symbol	Lines with hash prefixes + refs, one call
trueline_read	Need exact edit context	Per-line hashes + checksums; globs and path:range
trueline_edit	All edits	Hash-verified, atomic; built-in Edit blocked by hook
trueline_verify	Refs held across turns	Checks staleness without re-read
trueline_changes	Review vs git	Symbol-level semantic diff

Three workflows

Pick one matching what you know.

1. Surgical (default) — know the target

trueline_search(file_paths, pattern) → trueline_edit

No read step. trueline_search returns lines with hash prefixes plus ref. Feed straight into trueline_edit. Fastest. Use for renames, string swaps, bugfixes on named function.

2. Exploratory — need context first

trueline_outline → trueline_read (targeted ranges) → trueline_edit

Outline gives structure. Read only ranges you need. trueline_read accepts path:startLine-endLine inline for multiple slices in one call.

3. Re-entering — refs held across turns

trueline_verify(refs) → re-read only stale ranges → trueline_edit

Nothing changed → edit straight away. Stale → re-read just that range. Never re-read whole file on spec.

Worked example: search → edit

trueline_search output:

ab.10    old line one
cd.11    old line two
ref:R1

Replace both:

trueline_edit(
  file_path=…,
  edits=[{ range: "ab.10-cd.11", ref: "R1", content: "new line one\nnew line two" }]
)

• range uses hash.line identifiers verbatim from output.
• ref is short token (R1) — copy verbatim, never guess.
• Wide ref (e.g. lines 1-157) valid for any sub-range inside. Don't re-read narrower.

Load-bearing rules

Non-negotiable. Violations → verification errors or silent data loss.

• Never fabricate refs. Copy R1/R2/… directly from output. Made-up ref fails verification.
• Hash prefixes (ab.10) required. Not decoration — verify content at that line.
• action="insert_after" to add lines. Without it, range is replaced and content lost. To add next to existing lines, pass action: "insert_after".
• Don't re-read data you have. With ref and hash.line from prior search/read, go straight to trueline_edit.

Multi-file batches

Editing many files? Use Grep to find files, then pass all paths to one trueline_search call. Refs for every match in one round-trip.

Deferred tool loading

If trueline schemas deferred, load in one batch:

ToolSearch("+trueline read edit")

Loads all six schemas together. One call, not six.

Quick reference

• Exploration default: trueline_outline.
• Edit default: trueline_search → trueline_edit.
• Review changes: trueline_changes.
• Refs between turns: trueline_verify.