{"slug": "making-claude-code-concise-without-making-it-dumber-the-engineering-behind-two", "title": "Making Claude Code concise without making it dumber: the engineering behind two open-source plugins", "summary": "A developer built clear-claude, an MIT-licensed open-source marketplace of three Claude Code plugins that make the coding assistant more concise and improve its status line. The Clear Partner output style cut average answer length from 524 to 258 words across four runs per arm of three questions, while a 12-case behavioral eval suite scored 6/6 with the style and 6/6 without on Claude Code 2.1.274. The project also includes an experimental transcript layer built on Claude Code's undocumented function hooks.", "body_md": "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.\n\nEverything here is in [clear-claude](https://github.com/jessebldr/clear-claude) on GitHub, MIT licensed. Every number below is a measured one; where the measurement is weak, I'll say so.\n\nTwo annoyances, one root cause: Claude Code is honest but verbose, and its situational awareness is scattered.\n\n**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.\n\n**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.\n\nClear Claude is a marketplace with three layers, each owning one problem and nothing else:\n\n```\nClear Partner    → how Claude communicates        (prompt; plugins/clear-partner)\nClear UI         → what the user sees at a glance (statusline; plugins/clear-ui)\nClear Transcript → how the conversation is drawn  (function hooks; experimental/)\n```\n\nA standing design rule across all three: prompts for judgment, deterministic mechanisms for mechanics — and never solve the same problem in two layers.\n\nClear Partner is a Claude Code *output style*: a single Markdown file with a frontmatter block, loaded as the system prompt's communication layer.\n\n```\n---\nname: Clear Partner\ndescription: \"Clear, conversational technical partner. Answer-first, plain English, concise by default, deep when needed.\"\nkeep-coding-instructions: true\nforce-for-plugin: true\n---\n```\n\nThe file itself is ~4.6 KB of plain instruction. The core ideas:\n\nThat last rule exists because it was *measured* to be needed — more on that below.\n\nOne 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.\n\nThe 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.)\n\nWord 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:\n\n| Case | What it pins | \n|---|---|\n| a-correctness-preserved | The answer stays correct | \n| b-concise-by-default | Short by default | \n| c-depth-when-asked | Goes deep when asked | \n| d-no-style-leak | The style doesn't leak where it shouldn't | \n| e-workflow-multi-step | Multi-step work still works | \n| f-ambiguous-request | Asks instead of guessing on ambiguity | \n\nOn 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.\n\nThe 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**:\n\n| Case | 0.1.0 | 0.1.1 | Baseline |\n\n|---|---|---|\n\n| g-one-sentence | 1.00 | 1.00 | 1.00 |\n\n| h-just-the-command | 1.00 | 1.00 | 1.00 |\n\n| i-nothing-else-after-work | 1.00 | 1.00 | 1.00 |\n\n| j-constraint-keeps-safety-warning | 0.83 | **1.00** | 0.83 |\n\n| k-list-not-table-for-commands | 0.33 | **1.00** | 0.67–1.00 |\n\n| l-one-sentence-after-tool-use | 0.33 | **1.00** | 0.33 |\n\nTwo stories worth telling:\n\n**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.\"\n\n**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.\n\nAnd 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.\n\nOne 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.\n\nAlso 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.\n\nClear UI is a statusline script with a deliberate split. The entry point is a pipeline:\n\n```\nbin/statusline.mjs: read → gather → render → print → exit(0)\n```\n\n`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.\n\nWhat 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.\n\nThe 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.\n\nThe weekly-limit chip is the interesting engineering, because Claude Code's status-line JSON does not expose model-scoped usage. The provider's design:\n\n`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 `limits` data, never the rendered text. Why: offline with a stale snapshot, Claude Code prints the old percentages while the structured 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.\n\nThe 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.\n\nIt 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:\n\n```\nCLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude --plugin-dir experimental/clear-transcript\n```\n\n(Deliberately never exported, never written to a settings file.)\n\nWhat'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.\n\nThe 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.**\n\n`ctrl+o` (and `--verbose`) shows rows as the engine draws them — unconditionally for tool groups. For answers it's a `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.`/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.\nClear 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.\n\nThe marketplace is `clear-claude`. Installing one layer never installs another:\n\n```\nclaude plugin install clear-partner@clear-claude\nclaude plugin install clear-ui@clear-claude\n```\n\nClear Transcript has no install — `--plugin-dir`, as above.\n\n`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.\nThe 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.\n\n*Repo: [github.com/jessebldr/clear-claude](https://github.com/jessebldr/clear-claude) — MIT. Design docs, evals, and dogfood records all live in `docs/`.*", "url": "https://wpnews.pro/news/making-claude-code-concise-without-making-it-dumber-the-engineering-behind-two", "canonical_source": "https://dev.to/nguyen_jesse_8602dc05abd6/making-claude-code-concise-without-making-it-dumber-the-engineering-behind-two-open-source-plugins-3ll9", "published_at": "2026-09-22 15:07:07+00:00", "updated_at": "2026-09-22 15:23:21.128935+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools", "ai-agents", "large-language-models"], "entities": ["Claude Code", "Anthropic", "clear-claude", "Clear Partner", "Clear UI", "Clear Transcript", "GitHub"], "alternates": {"html": "https://wpnews.pro/news/making-claude-code-concise-without-making-it-dumber-the-engineering-behind-two", "markdown": "https://wpnews.pro/news/making-claude-code-concise-without-making-it-dumber-the-engineering-behind-two.md", "text": "https://wpnews.pro/news/making-claude-code-concise-without-making-it-dumber-the-engineering-behind-two.txt", "jsonld": "https://wpnews.pro/news/making-claude-code-concise-without-making-it-dumber-the-engineering-behind-two.jsonld"}}