terse-sharp

<h1 align="center">TerseSharp</h1> <p align="center"> <b>Roslyn for your coding agent. 86 tools over MCP.</b><br/> Your agent stops reading whole files, stops grepping for symbols, and stops turning the loop three times to learn one thing — so it finishes sooner, costs less, and can only emit code you would merge. </p> <p align="center"> <a href="https://www.nuget.org/packages/TerseSharp"><img src="https://img.shields.io/nuget/v/TerseSharp.svg?logo=nuget&label=NuGet" alt="NuGet"/></a> <a href="https://www.nuget.org/packages/TerseSharp"><img src="https://img.shields.io/nuget/dt/TerseSharp.svg?logo=nuget&label=downloads" alt="Downloads"/></a> <a href="https://github.com/amusleh-spotware-com/terse-sharp/actions/workflows/ci.yml"><img src="https://github.com/amusleh-spotware-com/terse-sharp/actions/workflows/ci.yml/badge.svg" alt="CI"/></a> <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="MIT"/></a> <img src="https://img.shields.io/badge/.NET-10-512BD4.svg?logo=dotnet&logoColor=white" alt=".NET 10"/> <img src="https://img.shields.io/badge/tools-86-26C281.svg" alt="86 tools"/> <img src="https://img.shields.io/badge/tokens-10--30×_fewer-26C281.svg" alt="10-30x fewer tokens"/> </p> <p align="center"> <a href="#-token-saving--46m-tokens-in-one-week-measured">Token saving</a> · <a href="#-speed--fewer-turns-of-the-loop">Speed</a> · <a href="#-code-quality--the-gate-your-agent-cannot-skip">Code quality</a> · <a href="#-control--what-your-agent-may-and-may-not-emit">Control</a> · <a href="#-your-stack--blazor-xaml-minimal-apis-localization">Your stack</a> · <a href="#-install">Install</a> · <a href="#-all-86-tools">Tools</a> </p>

- Grep "Submit" → 40 hits → Read OrderService.cs (2,000 lines) → Read the three callers → Edit by line
+ find_usages OrderService.Submit          → 6 real references, each tagged EXACT, ~200 tokens, one call

---

🎯 Five reasons it is installed

| | What it does | The number | |---|---|---| | 💸 Token saving | Answers semantically instead of dumping text — outlines, symbol ids, one record per line | 4.56M tokens never sent in one measured week — 2.9× the entire bill | | ⏱️ Speed | Deletes round trips: batched reads, batched edits, one compile gate, concurrent test projects | a round trip costs 6.1 s of model latency before the tool runs; run_tests 38 % faster | | 🧪 Code quality | Every edit is compile-gated and rolled back if it breaks; gate runs analyze → format → cleanup → analyze again in one call | a broken edit never reaches your branch | | 🚦 Control | .terse.json policy can reject code that compiles but isn't mergeable; the guard denies Read/Grep/dotnet build; --read-only freezes everything | 14 rules, TERSE100–TERSE113, ReSharper's own defaults | | 🧩 Your stack | Blazor/Razor, XAML for MAUI · WPF · WinUI · Avalonia, ASP.NET Core Minimal APIs, .resx localization, DI containers | answers what the compiler itself cannot check |

---

💸 Token saving — 4.6M tokens in one week, measured

508 Claude Code sessions, one developer, one week, one 31,000-file C# solution — replayed from the raw transcripts. Every one of the 6,045 TerseSharp calls was re-priced against the built-in it replaced: Read against the real file on disk, Grep against a real ripgrep run of the same query, build / run_tests / git diff against 3,767 real dotnet and git invocations.

| | tokens | |---|---| | What the 6,045 TerseSharp calls actually cost | 2.41M | | What Read / Grep / Bash would have cost for the same answers | 6.97M | | Burned for nothing, had it not been installed | 4.56M — 2.9× the entire bill |

Then it compounds. Every token put into context was re-sent 33× (4.41B cache-read against 132.6M cache-write), so 4.56M tokens never injected are ~150M never re-read.

Per question, this is what the difference looks like:

| Question | Built-in tools | TerseSharp | | |---|---|---|---| | What's on this 2,000-line type? | Read → ~6,000 tok | get_type_outline → ~450 tok | 13× | | Read a whole .cs file | Read → the entire text | read_text answers the outline unless you ask for text | 3× | | Who calls this method? | Grep + follow-ups → ~4,000 tok | find_usages → ~200 tok | 20× | | Rename across the solution | ~5,000 tok, misses the interface | rename_symbol → ~150 tok, correct | 30× | | Why is the build red? | ~8,000 tok of MSBuild spew | build → ~600 tok | 13× | | What did I just change? | git diff → the whole patch | diff_symbols → the changed declarations | 10× | | Which rows does this checked-in table hold? | Read the whole .md, then grep it | read_text columns="Finding,Tool" cellChars=60 | ~10× | | What does this budgeted doc cost in tokens? | a build plus the E2E suite → ~10 min | read_text tokens=true → ~3 s | 200× | | Does this {Binding} bind? | no static answer exists in WPF | xaml_bindings validate=true | ∞ |

_{Asserted by a token-budget suite on every push, not estimated.}

Success costs nothing. Every mutating tool answers in one line per changed file — verbose=true returns the diff, dryRun=true previews it. Any caveat, rollback, timeout or zero-result run prints in full, because condensing a result that carried a caveat is a wrong answer the agent cannot detect. A .terse.json policy WARNING is payload, so it rides on the one-line answer.

<details> <summary>Per-call breakdown, the pessimistic floor, and the two tools that lost</summary>

| The call | Built-in would cost | TerseSharp cost | | |---|---:|---:|---:| | find_implementations × 72 | 192k tok | 4k tok | 44.9× | | find_usages × 274 | 1.26M tok | 111k tok | 11.4× | | ranged read_text × 446 | 1.59M tok | 308k tok | 5.2× | | get_file_outline × 162 | 402k tok | 112k tok | 3.6× | | search_symbols × 520 | 860k tok | 272k tok | 3.2× | | get_symbol_source × 630 | 1.26M tok | 405k tok | 3.1× | | build × 165 | 32k tok | 10k tok | 3.1× | | whole-file read_text × 930 | 1.04M tok | 881k tok | 1.2× | | run_tests × 393 | 80k tok | 66k tok | 1.2× |

The floor. Push every assumption against TerseSharp — ranged reads priced as a perfect Read offset/limit, searches priced at the median grep output instead of the mean — and the saving is still 2.09M tokens, 1.9×. analyze, search_text, every edit tool and the whole .resx / XAML / Razor surface were scored zero, and no grep→Read follow-up chain was charged to the built-ins.

What lost. diff_symbols (13 calls) and list_tests (3) cost more than the raw command. Measured, logged in the backlog, not hidden.

</details>

---

⏱️ Speed — fewer turns of the loop

An agentic task is a loop: emit a call, wait, read the answer, emit the next one. Two things decide how long it takes — how many times the loop turns, and how much each answer costs to read.

Mined from one week of real Claude Code sessions — 305 transcripts, 36,075 tool calls — every round trip costs 6.1 s of model latency before the tool even runs. So a tool that deletes a call beats one that merely shortens a response, and both beat a faster server.

| Instead of | One call | |---|---| | grep, open the hit, open its callers | find_usages — real references, each tagged EXACT or HEURISTIC | | read the file to find the member, then read the member | get_file_outline → paste the id straight into get_symbol_source | | one search per identifier | search_text queries=[…] — 8 literals, one pass, records tagged q1..qN | | a text hit, an outline, then a ranged read to find the method it sits in | search_text containers=true — the declaration on the record itself | | trace a symbol by hand across the solution | get_symbol usages=true · find_usages impact=true — definition, usages, implementations, blast radius | | git describe to find where HEAD sits before a release | history describe=true — nearest tag, commits since it, short sha, dirty flag, one line | | one read per file | read_text paths=[…] — up to 10 files, one answer | | one ranged read per anchor in the same file | read_text ranges=["42", "101-102"] — discontinuous ranges, one answer | | one edit call per site | edit_text edits=[…] — 25 edits across files, one write | | re-sending a previewed, rolled-back or force-refused write | write_text retryWith=r3 — the payload is held, the retry sends none | | edit, build, find you broke a caller, edit again | replace_symbol symbolIds=[…] — the member and its callers land in one compile gate | | grep the test tree and guess what to run | find_usages impact=true tests=true — ready-made run_tests test= arguments | | one search per glob | search_text paths=["src/**/*.cs", "**/*.md"] — globs OR-ed into one file set, one answer | | dotnet test per project, serially | run_tests projects=[…] — concurrent, one process per core | | a run_tests past the client's foreground limit, polled with TaskOutput | a plain run_tests where the client moves long calls to the background and notifies (Claude Code); elsewhere run_tests detach=true answers an id at once and run_tests status="<id>" waitSeconds=3600 waits for the verdict - nothing notifies a detached run, and run_tests status="cancel" stops a run whose caller stopped waiting |

And the waiting itself is shorter. A bare run_tests over a solution builds once, then runs each test assembly directly where its runner allows — no MSBuild evaluation and no VSTest host per project — measured 38 % faster over five alternating pairs. A green run_tests repeated with nothing written since is not re-run at all: it answers UNCHANGED with the previous verdict and its age; a repeat that re-runs anyway names what moved in one NOTE re-ran: line. From the second consecutive call of the same tool, the response adds one 14-token line naming the plural you should have passed.

Parallel by default where it is safe. Every read tool — analyze included — declares the MCP readOnlyHint annotation and every deleting tool declares destructiveHint, so a client that gates parallel dispatch on those hints — Claude Code does — fans the reads out instead of running them one at a time. The build and test tools are deliberately off that list: a build dispatched beside an edit is a race, not a saving.

---

🧪 Code quality — the gate your agent cannot skip

An agent that writes code it cannot verify is a liability. TerseSharp holds the Roslyn compilation, so it verifies before it reports success.

• 🛡️ Compile-gated edits. Every C#, Razor and refactoring edit is applied, re-analyzed, and rolled back if it introduces a compile error — in the changed projects and every project that transitively depends on them. The agent never gets to say "done" over a red tree. undo_last_change reverses the last one; allowErrors=true is the explicit opt-out.
• 🧭 Semantic, never textual. Real references, not string matches — every record tagged EXACT or HEURISTIC, so you always know what you are trusting.
• 🧾 No silently-ignored arguments. A parameter a tool does not declare is refused by name; a listing that quietly dropped your maxResults is a wrong answer the agent cannot detect.
• 🚫 Never guesses. Where it cannot prove an answer it says so — AmbiguousSymbol, SaturatedName, UNRESOLVED_CONTEXT, NOT rewritten. A false positive costs an agent more than no answer.
• 🔄 Always fresh. A file you just created, or an edit from your IDE, is already in the next answer — no reload, no stale index.

One call runs the whole ladder in the mandated order and answers one verdict line:

gate                 →  analyze at info severity → format → cl