Conversation
Benchmarks → bench/README.md (shown when browsing bench/); the write-time essay → docs/why-write-time.md; the compression reference (per-type contract, ML prose path, architecture, performance, limitations) → docs/compression.md. Verbatim moves with relative links fixed; the README rewrite links each from a distilled summary. Depth gains a durable home instead of burying the front door. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Researched 9 high-traction dev-tool READMEs (uv, aider, ollama, httpie, litestream, ripgrep, fzf, bat, zoxide) + community guidance. The convergent formula among modern breakouts: 5-line hero (one sentence + visual-as-argument), scannable benefit Highlights, install within ~150 words, progressive disclosure (README sells and starts you; depth lives in linked docs), FAQ, 800-1,500 words. Ours was 447 lines / 3,206 words with 378 words before the install command, value props buried in prose, and 120+ lines of benchmarks/essay mid-file. Now: 113 lines / 1,168 words. Hero covers both surfaces in one sentence; 7 Highlights bullets; install + optional-router quickstart up top; one headline number (22% @ zero measured loss) with receipts linked; distilled sections per surface linking bench/README.md, docs/compression.md, docs/ROUTER.md, docs/why-write-time.md; FAQ harvested from Known limitations (incl. the honest tokens-vs-dollars and vs-headroom answers — personality preserved); Verify-it- yourself kept as the credibility differentiator. All 12 relative links verified; the #model-routing-opt-in anchor docs/ROUTER.md depends on is preserved. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Requiring WHITTLE_ROUTER_MODEL_URL to enable ML routing was an installation footgun (observed live: a router launched without it silently ran heuristics- only). The router now defaults to the standard sidecar address `whittle setup` installs (127.0.0.1:45872); the env var is an override, "off" disables. The design problem with a default URL is absence semantics: a never-installed sidecar must not spam errors. Split by cause: connection REFUSED = expected absence → reads as smart-mode-off (signals trace "off", no ml-degraded, quiet); listening-but-broken (timeout/5xx/malformed) = real degradation → stays loud. The absence check is per-request and free (localhost refusal is immediate), so signals activate the moment the sidecar appears — no restart. One startup probe prints an honest mode line either way. launchd plist no longer carries env plumbing; help + docs/ROUTER.md updated. Tests pin absent-vs-broken semantics + absence-not-degraded end-to-end. Verified live on all three paths (zero-config → casual-easy→haiku; dead port → quiet heuristics; off → warning). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
'Cut your token bill twice' read awkwardly — replaced with the carving identity covering both surfaces: 'Carve your AI agent's context down to what matters — and route every request to the cheapest model that can handle it.' Credits made specific so nobody reads the router as derived work: the two pretrained models (the 14-subject domain classifier and the text embedder) come from vLLM Semantic Router; the engine, policy design, and signal composition are whittle's own — stated in both the router section and Acknowledgments. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Replace the README hero with a pre-sized, append-only ANSI stream that replays a real captured session: four agent turns routed to the right model (opus held on hard reasoning, haiku/sonnet on trivia and drafting) while tool outputs are carved losslessly, closing on a `whittle stats` session summary. All color comes from demo/hero-feed.sh's stdout (a plain sh script using printf + sleep, reproducible from a clone); demo/hero.tape drives VHS, typing `whittle watch` (a hidden session alias for the replay) so the frame reads as whittle's own live output. One clear, no scrolling, CursorBlink off — 168KB, 24s, 1000x600. Numbers are measured, not guessed: 21,980 tokens carved is (1,904−47)+(20,595−472); ~$0.05 saved is the real billed-token delta of the two down-routed turns at current per-family list prices. stats.gif is unreferenced but left in place; compress.gif still backs "See it". Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this does
Two onboarding improvements, both aimed at the 30-second first impression:
README rewrite (research-driven)
Measured the READMEs of 9 high-traction dev tools (uv, aider, ollama, httpie, litestream, ripgrep, fzf, bat, zoxide) plus community guidance. The convergent formula among modern breakouts: a 5-line hero, scannable benefit Highlights, install within ~150 words, one headline number with receipts linked, an FAQ, and 800–1,500 words total with depth living in linked docs.
bench/README.md(renders when browsingbench/), the write-time essay todocs/why-write-time.md, the compression reference todocs/compression.md. All 12 relative links verified; the anchordocs/ROUTER.mddepends on is preserved.domainclassifier and the text embedder) come from vLLM Semantic Router; the engine, policy design, and signal composition are whittle's own.Zero-config smart routing
whittle routepreviously requiredWHITTLE_ROUTER_MODEL_URLto enable ML signals — a footgun we hit live (a router launched without it silently ran heuristics-only). Smart mode is now automatic: the router defaults to the sidecar addresswhittle setupinstalls, and absence semantics are split by cause:off, no error spam, heuristics still route — and ML activates the moment the sidecar appears, no restart (the check is per-request and free on localhost).errtraces +ml-degraded.WHITTLE_ROUTER_MODEL_URLis demoted to an override (offdisables). The launchd plist drops its env plumbing. Tests pin absent-vs-broken and absence-not-degraded; verified live on all three paths.The router quickstart is now, in full:
🤖 Generated with Claude Code
Hero GIF: one live stream, both surfaces
Replaced the stats-chart hero with
demo/hero.gif(164 KB, 24s loop) — a singlewhittle watch-style terminal stream where routing verdicts and compression events interleave the way a real session interleaves them:"bigest country in europe?"→ greenopus→haiku;"What is in embed.go file?"→ blueopus→opus keptwithembed.go · untouched; a build.log carved live (the two red ERROR lines survive,[118 lines omitted],1,904 → 47 tok · −97%); slack draft → cyanopus→sonnet; closing tally21,980 tokens carved · ● haiku 2 ● sonnet 1 ● opus 1 held · ~$0.05 measured.Every number is a real measured figure from live sessions (the dollar was independently recomputed from logged tokens at list prices, per the design's truthfulness rule — no invented savings). Built with the repo's existing VHS pipeline (
demo/hero-feed.sh+demo/hero.tape), fully reproducible from a clone; designed append-only/no-scroll so the file stays tiny. Storyboard by the design pass, frames visually verified before shipping.