uditakhourii / quicksilver

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:

  1. paste it in chat. Then run qs setup <KEY> (it verifies the key, then
     saves it to ~/.quicksilver/config.json, user-only permissions), or

  2. 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.

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.