Quicksilver: let Jev make the calls, Claude does the thinking
Jev returns typed judgments (yes/no probability, one-of-N label, rubric score)
in about a second, at $0.042 per million input tokens. It cannot write text or reason in
steps. So the split is simple: Jev narrows, Claude reads only what survives.
Every item Jev rules out is content that never enters Claude's context. That
saves tokens, saves usage limits, and cuts wall-clock time, because Jev scans
hundreds of items in parallel.
In the commands below, qs stands for:
node "<base directory of this skill>/scripts/qs.mjs"
Needs Node 18+ (globs need Node 22+). There are no other dependencies.
First run: set the key once
Run qs status first.
-
ready means go straight to the task.
-
not configured means ask the user for their Jev API key, and point them to
https://console.typesafe.ai to create one. They can:
- paste it in chat. Then run
qs setup <KEY> (it verifies the key, then
saves it to ~/.quicksilver/config.json, user-only permissions), or
- keep it out of the chat by running
node "<skill dir>/scripts/qs.mjs" setup
in their own terminal. It prompts for the key with hidden input.
JEV_API_KEY or TYPESAFE_API_KEY in the environment also works, and takes precedence.
After setup, carry on with the original task. Don't stop at "configured".
Exit code 3 means a key problem: missing, or rejected by Jev. Re-run setup.
When to delegate
Ask: "Am I about to read a lot of content only to decide which parts matter?"
If yes, and each decision fits yes/no, pick-a-label, or rate-on-a-scale, delegate.
| Situation | Command |
|---|
| "Which files deal with X?" across a repo | qs filter "Does this file implement or handle X?" src |
| Errors or anomalies in a big log | qs filter "Does this line indicate a failure?" app.log --lines |
| Where in a 5k-line file is Y? | qs find "Y" big_file.py --top 5 |
| Sort 200 tickets, test failures, or TODOs into buckets | qs classify --labels "bug,feature,question" --items items.jsonl |
| Best candidates for a query (search hits, docs, files) | qs rank "query" docs/ --top 10 |
| One yes/no over a large document | qs ask "Does this contract allow termination without notice?" --state @contract.txt |
| Several questions over the same content | qs ask spec.json (raw request, see below) |
Benchmarked strengths (12 real tasks, see the repo's bench/): Quicksilver matched Claude's
accuracy while cutting its tokens by 77–96% on needle-in-haystack log search, finding
files across a repo, "where is X?" ranking, semantic search inside huge files, and bulk
routing or classification with clear labels (support intents, CI failure causes,
sentiment). It was weaker on subjective or expert-defined labels (commit types, alert
policies) and on look-alike code (safe vs vulnerable twins). There, use its output as a
shortlist, and check the ? items yourself.
Don't delegate:
- Tiny inputs (a few files, or under ~2k tokens). Just read them.
- Exact matches.
grep or rg is free and exact. Jev is for meaning: "handles
auth" rather than the literal string auth.
- Arithmetic, counting, date or time comparison. Do those in code.
- Anything generative (writing, summarizing, editing) or needing a chain of reasoning.
- Content the user wouldn't want sent to a third-party API. Quicksilver already
skips
.env*, keys, certs, and credentials files, and respects .gitignore.
Commands
Inputs (for filter, classify, rank): files, directories (respects
.gitignore inside git repos, and skips node_modules, dist, and similar),
globs, - for stdin, or --items FILE.jsonl (one JSON object per line with
id and text, or plain text lines). Add --lines to judge each line
separately (logs, CSVs, lists). Use --ext ts,tsx to limit file types.
qs filter "<yes/no question>" <inputs> [--threshold 0.5] [--lines]
qs classify --labels "a,b,c" <inputs> [--question "..."] [--only a] [--min-confidence 0.6]
qs classify --labels-json '{"bug":"Something is broken","feature":"A request for new behaviour"}' <inputs>
qs rank "<query>" <inputs> [--top 10 | --all]
qs find "<what you're looking for>" <files> [--top 5]
qs ask "<question>" --state @file|"text"|- [--choice "a,b,c" | --score "low|mid|high"]
qs ask spec.json # {"state": ..., "questions": {"id": {"type": "noul|choice|score", ...}}}
qs status # key check, plus lifetime tokens saved
Add --json to any command for machine-readable output. Summary lines go to stderr.
--save FILE writes every per-item result to FILE, while stdout stays compact.
--fast packs small items into shared requests. It's about 10× faster on big logs, but
less accurate on subtle judgments. Use it for obvious needles (crashes, OOMs) in very
large logs, not for classification.
Reading the output
Output is compact on purpose. For filter, each line is a probability, then the item.
With --lines, repeated log lines that differ only in numbers or ids are merged into
one pattern, followed by the matching line numbers:
0.99 src/db.ts
0.98 app.log:813 worker ERROR process killed: JavaScript heap out of memory
0.97 ×57 app.log:104 RAS KERNEL FATAL data TLB error interrupt
also lines 115,121-130,…
? borderline (0.35–0.65) — check these yourself:
0.55 app/api/convert_safe.ts
— 340 scanned · 3 matched · 1 borderline · 4.1s · jev 90k tok ($0.0038) · ~88k Claude tokens not read
classify prints the count per label, then the ids in each label. After that it lists
each low-confidence item with its runner-up label and its text:
bug 41 · feature 12 · question 7
[bug] T1 T4 T9 …
? low confidence — check these yourself:
?0.49 bug (or question) T33 login button does nothing on Safari?
? marks a borderline or low-confidence item. Read those yourself. In the
benchmark, the false positives sat in this band. Treat everything else as a
reliable shortlist.~ after an item means it was truncated past --max-chars (default 60k chars),
so Jev only saw the start.- The footer shows cost and the estimated Claude tokens avoided. Mention the
savings to the user when they're meaningful.
- Jev's verdicts make a shortlist, not proof. Open the survivors before you
edit code, draw conclusions, or tell the user something is definitely absent.
If a filter returns nothing you expected to find, rephrase the question or
lower
--threshold before concluding.
Writing good questions
Jev reads questions literally. Its accuracy comes from how precise the question is.
- One judgment per question. Say "Does this file send email?", not "Does this file
send email or handle billing?". Run two filters instead.
- Spell out the exact condition, including the boundary cases: "Does this line
report a failure (ERROR, FATAL, crash, timeout). Not warnings about deprecation?"
- Use plain meaning, not jargon hops or double negatives.
- Give classify labels short descriptions with
--labels "bug:Something broken,feature:New behaviour request".
Add a catch-all label such as other when nothing may fit.
- For a raw
ask spec, put the content in state (JSON objects are fine) and refer
to fields in backticks inside instructions, like `ticket.body`. Questions
run in parallel and can't see each other's answers. See
https://docs.typesafe.ai/api.md for the full schema.
Patterns that pay off
- Funnel:
qs filter over the whole repo, then Claude reads the 5 survivors
instead of 300 files.
- Log triage:
qs filter ... --lines over a 50k-line log, then Claude
investigates only the failures.
- Two-pass precision: a cheap broad
filter, then rank the survivors
against the specific question.
- Batch triage: dump items to JSONL (issues, test output, grep hits),
qs classify, then act per bucket.
Jev handles 1,200 requests/min. Quicksilver packs small items into shared
requests, runs 8 in parallel, and retries rate limits (429/529) automatically.