Making Claude Code concise without making it dumber: the engineering behind two open-source plugins

Nguyen Jesse — Tue, 22 Sep 2026 15:07:07 +0000

Claude Code talks too much, and its status bar tells you nothing. So I built two open-source plugins to fix both — and a third, experimental one that redraws the transcript itself. This is the engineering: how the conciseness layer works, how it's measured, why the status bar is architected the way it is, and what building on Claude Code's undocumented function hooks actually looks like.

Everything here is in clear-claude on GitHub, MIT licensed. Every number below is a measured one; where the measurement is weak, I'll say so.

The problem

Two annoyances, one root cause: Claude Code is honest but verbose, and its situational awareness is scattered.

Annoyance 1: the talking. Ask a simple question and you get a preamble, a narration of the plan, the answer somewhere in the middle, and a summary of what was just said. The naive fix — "be concise" — teaches the model to drop things: the warning, the exact number, the assumption, the tradeoff. You get a shorter answer and a worse one. Most brevity prompts quietly make the model shallower.

Annoyance 2: the status line. Claude Code exposes genuinely useful state — model, context window, 5-hour and weekly usage — but it's scattered across the footer, the spinner, /usage, /context, and the shell. Before every long task you're reconstructing the situation from fragments: how much room is left, when quota resets, whether the repo is dirty.

Clear Claude is a marketplace with three layers, each owning one problem and nothing else:

Clear Partner    → how Claude communicates        (prompt; plugins/clear-partner)
Clear UI         → what the user sees at a glance (statusline; plugins/clear-ui)
Clear Transcript → how the conversation is drawn  (function hooks; experimental/)

A standing design rule across all three: prompts for judgment, deterministic mechanisms for mechanics — and never solve the same problem in two layers.

Clear Partner: the output style

How it works

Clear Partner is a Claude Code output style: a single Markdown file with a frontmatter block, loaded as the system prompt's communication layer.

---
name: Clear Partner
description: "Clear, conversational technical partner. Answer-first, plain English, concise by default, deep when needed."
keep-coding-instructions: true
force-for-plugin: true
---

The file itself is ~4.6 KB of plain instruction. The core ideas:

Answer first. Lead with the actual answer, result, or recommendation. No filler, no acknowledgements, no narration of what's about to happen.
Economical in what the user reads, never in the work. This is the line that separates it from "be concise": do all the investigation, reasoning, coding, and verification the task requires — then spend as few words as possible reporting it. Concise does not mean incomplete. Never drop a warning, constraint, assumption, exact number, scope condition, or important tradeoff merely to be shorter.
Explicit constraints outrank every default. If the user says "one sentence", "just the command", or "nothing else", that beats the style's own habits — including the completion report after implementation work. The one exception is a safety-critical warning (data loss, security risk, irreversible action): keep it as a single short line, add nothing else. No alternatives, no flag explanations, no follow-up tips.

That last rule exists because it was measured to be needed — more on that below.

The measurement: 524 → 258 words

One recording is an anecdote, so the headline number comes from repeated runs: four runs per arm of three everyday questions averaged 524 → 258 words (−51%), and no plugin answer was as long as the shortest stock answer to the same question.

The methodology is deliberately boring: same three questions, four runs each, both arms, word counts averaged. And here's the part most projects would leave out — the repo also records an earlier take where the plugin's answer came out longer than stock, plus the raw outputs and the exact flags. When the data is embarrassing, it's still data. (demo/README.md has all of it.)

The evals, and their honest limits

Word count is a proxy; the real question is whether the style breaks anything. There's a behavioral eval suite (plugins/clear-partner/evals/, run with claude plugin eval) of 12 cases. The first six pin the basics:

Case	What it pins
a-correctness-preserved	The answer stays correct
b-concise-by-default	Short by default
c-depth-when-asked	Goes deep when asked
d-no-style-leak	The style doesn't leak where it shouldn't
e-workflow-multi-step	Multi-step work still works
f-ambiguous-request	Asks instead of guessing on ambiguity

On Claude Code 2.1.274: 6/6 with the style, 6/6 without. Re-run on 2.1.278 (same prompt, no edits): 6/6 with the style, $1.54, 342 seconds. The baseline arm failed one case — and this is where the honesty matters: the baseline didn't answer badly, it ran out of turns on the ambiguous request, so there was no final message to grade. One run per arm can't tell a tendency from chance. The repo records it as "baseline errored once" and the claim stays what it was: the style does not break anything. Not "the style is better". There is a difference, and it matters.

The second six cases (g–l) are regression cases born from real demo failures. The shipped style was ignoring explicit user constraints: "in one sentence" came back as two or three sentences, and a question about commands came back as a table whose cells wrapped in a terminal pane. Each failure became a case first, run against the shipped prompt, and the prompt was edited only where a case failed:

| Case | 0.1.0 | 0.1.1 | Baseline |
|---|---|---|
| g-one-sentence | 1.00 | 1.00 | 1.00 |
| h-just-the-command | 1.00 | 1.00 | 1.00 |
| i-nothing-else-after-work | 1.00 | 1.00 | 1.00 |
| j-constraint-keeps-safety-warning | 0.83 | 1.00 | 0.83 |
| k-list-not-table-for-commands | 0.33 | 1.00 | 0.67–1.00 |
| l-one-sentence-after-tool-use | 0.33 | 1.00 | 0.33 |

Two stories worth telling:

Case k caught the style being worse than stock. Its old line — "use a table when comparison is easier in rows and columns" — made it more table-prone than baseline: in the recorded demo runs it answered the disk-space question with a table 4 times out of 4; stock did it 0 times out of 4. The rule is now "a table only for a real comparison."

Case l failed 4/4 on the old prompt and on stock Claude Code: after real work on a multi-part subject, the habit of covering every part beat "one sentence". That's what produced the "explicit constraints outrank every default" rule.

And the stated limits, quoted from the eval doc: three or four runs per arm show a tendency, not a rate. Case k's baseline drifted between 0.67 and 1.00 across suite runs because its first LLM grader was judging formatting it should have left to the regex — it was narrowed before the 0.1.1 run. The numbers are small; the repo says so.

One more integrity mechanism: the style file's SHA-256 is recorded (docs/clear-partner-port.md), so you can verify the prompt you're running is the prompt that was measured. v0.4.1 fixed false eval failures caused by incorrect style-shadowing assumptions — prompt bytes unchanged.

Also in the box: /clear-partner:clear-doctor and /clear-partner:clear-audit, read-only diagnostic skills. Read-only by design, and they stay that way — a doctor that fixes things is explicitly on the "not planned" list.

Clear UI: the status bar

Architecture: a pure core with a thin shell

Clear UI is a statusline script with a deliberate split. The entry point is a pipeline:

bin/statusline.mjs: read → gather → render → print → exit(0)

src/render.mjs is pure: (state, options) → string[]. No I/O, no Node API. state.mjs, sanitize.mjs, and layout.mjs are pure too. Everything impure — bounded stdin reads with timeouts, one git call with a TTL cache, the usage cache file — lives at the edges. This means the entire visual output is unit-testable as a function, including golden tests, and the timing-critical path (render) can never block on the network or a subprocess.

What the bar shows: model, project and git branch with a dirty dot, context percentage, 5-hour and weekly usage — plus the sleeper feature, an opt-in chip showing your model's weekly limit. Zero dependencies. In its default mode it reaches no network and reads no credentials.

The measured budget: on an M4 Mac mini, bench/bench.mjs read 38 ms with git cached, 46 ms on a cache miss, median of three runs (38/46, 38/45, 38/46). That budget is documented in the changelog, not just claimed in a tweet.

The usage provider: a cache-file contract

The weekly-limit chip is the interesting engineering, because Claude Code's status-line JSON does not expose model-scoped usage. The provider's design:

The status line never calls anything. It only reads a cache file. Rendering is decoupled from fetching — the render path can never stall.
A detached worker refreshes at most every ten minutes. It claims the refresh with an exclusively-created lock file named after the interval, so the two-second ticks of every open session start exactly one worker between them. A failed refresh isn't retried until the next interval.
The fetch itself runs Claude Code's own claude -p /usage. /usage is a built-in that makes no model turn and costs nothing — but it's undocumented as a machine interface, so the provider trusts only its structured limits data, never the rendered text. Why: offline with a stale snapshot, Claude Code prints the old percentages while the structured limits is null. The text can't be told from an answer; the structured data can be told from nothing.
Fail closed, always. The last good answer is drawn for 30 minutes — three missed refreshes — and then not at all. A window that has reset since the fetch is dropped at once. If the provider can't vouch for the number, the chip disappears instead of lying.

The $0.136 lesson

This design exists because of a real failure. During headless research, Git Bash rewrote the leading-slash /usage into a path — C:/Program Files/Git/usage — which is a prompt, which a model answered, for money. $0.136. The fix: the whole argument vector is passed to spawn as an array and never through a shell — a shell is how /usage stops being a command. There's now a regression test that prevents that route (docs/research/headless-usage.md tells the full story). Every refresh is also a full Claude Code start (~1.9 s, in the background, reaching the network) — which is why it's opt-in and why it's never done more often than the number can change.

Clear Transcript: the function-hooks experiment

The third layer redraws the conversation itself: a settled group of tool calls names its files and commands — Read sum.mjs, format.mjs, parse.mjs — where stock draws Read 3 files, ran 2 shell commands; a failed call gets a line of its own; section titles in a long answer are underlined, where stock draws every heading level the same.

It stands on function hooks ("Claude Mods"), which Anthropic has not documented or switched on. So this layer is experimental: not in the marketplace, no install command, runs from a clone with --plugin-dir and a gate env var:

CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude --plugin-dir experimental/clear-transcript

(Deliberately never exported, never written to a settings file.)

What's genuinely interesting here is the honest accounting of how much of the conversation can be improved today, measured against Claude Code 2.1.278. The hook surface only raises render sites for some rows — AssistantMessage, ToolGroup — and for others there is simply no site. The doc (docs/clear-transcript.md) tabulates every part of the conversation: what has a render site, what Clear Transcript redraws, and what it leaves to the engine. The answer: two rows, redrawn conservatively, and a rule for everything else. The platform could carry more — folds, labels, a reader pane, accent colours — and each was refused on evidence.

The interaction model is one sentence: the normal view is Clear Transcript's; the expanded view (ctrl+o) is Claude Code's; any doubt is Claude Code's.

Nothing is folded, capped, or hidden — a transcript row has no keyboard focus, so there's no way back needed to read, only to audit.
ctrl+o (and --verbose) shows rows as the engine draws them — unconditionally for tool groups. For answers it's a learnt view: the mod watches UserMessage.isExpanded, re-asks for every row when it flips, and passes while true. One stated edge: an expanded view where no prompt row is raised at all would leave an answer's titles underlined there — same words, one attribute different. Never met in any recording; can't be ruled out from the types. It's documented as an edge rather than hand-waved.
/clear-transcript off restores stock in place, unconditionally, and answers with text only and no context — the model never hears of it.
The stored message is never touched. /copy and export read what the model wrote. A refused tree is the stock row: the engine validates every tree and draws its own on any refusal, so there is no broken-row state to design for.

Clear Transcript is finished work waiting for Anthropic to stabilise an API — not a preview of unfinished work. Version 1.0 waits for function hooks to become documented, stable, and on by default. Clear Partner and Clear UI will never depend on it.

Install

The marketplace is clear-claude. Installing one layer never installs another:

claude plugin install clear-partner@clear-claude
claude plugin install clear-ui@clear-claude

Clear Transcript has no install — --plugin-dir, as above.

What's next

Official Claude Code marketplace submission — the plugin directory submission is pending; the tracking issue is public on the repo.
Clear Transcript 1.0 — when (if) Anthropic documents and enables function hooks by default, the experimental layer graduates.
More of the same honesty — the roadmap is public (docs/roadmap-v2.md), the evals record their own limits, and the "not planned" list is explicit: no auto-fixing doctor, no bundle plugin, no Intel Mac timing claims without an Intel Mac.

The through-line of the whole project: be economical in what the user reads, never in the evidence. If you try it and the numbers don't hold on your machine, the issue tracker is open, and a reproduction beats an opinion.

Repo: github.com/jessebldr/clear-claude — MIT. Design docs, evals, and dogfood records all live in docs/.

DEV Community: Nguyen Jesse