Claude Skills by zapgun-ai

Run a counterbalanced A/B knob block end to end and produce a report. Orchestrates the whole validation loop the other skills do piecemeal — for each arm it starts a clawback proxy with that arm's knobs and its OWN --state file (fresh SESSION KEY, no clawback-side carry-over), drives N turns of load through it (pty or replay driver), stops it, then analyzes the per-arm turn-logs and renders the charts. No cache-salt: production forwards none, so neither does the harness. Default block is A0 (...

Fast, read-only per-arm turn-log summary — billable turn count, httpStatus tally (catches rate-limiting / non-200s mid-run), cache_read/creation sums with the ephemeral 5m-vs-1h split (a direct knob-sanity check: A2/A3/A5 should show ephemeral_1h > 0, A0/A1/A4 should not), token-weighted hit rate, and thinkingBudget. Unlike the heavyweight `bench` analyzer it does no bootstrap/CI/pricing, so it is cheap to run at each arm boundary WHILE a suite is still in flight. Safe on a live, actively-app...

Analyze clawback turn-logs (NDJSON) to compare treatment vs passthrough arms. Produces report.md, report.csv, summary.json, manifest.json. Headline is billable input tokens reclaimed per turn (full-rate quota saved, no pricing) with a bootstrap 95% CI; per-turn $ and hit-rate are a demoted cost appendix, all stratified by inter-turn gap bucket. Use after the operator has collected counter-balanced windows.

Capture a REAL Claude Code /v1/messages body as a replay fixture, so the HTTP replay arm (.skills/replay) faithfully reproduces Claude Code's cache_control breakpoint structure (a hand-authored fixture makes the 1h-TTL knob look like a no-op). Starts a clawback proxy with --capture-body, drives ONE real claude turn through it via the PTY driver, verifies the dump carries cache_control breakpoints, and promotes it to the fixture path. Spends real Anthropic tokens (exactly one turn; pin a cheap...

Render the clawback share card in BOTH tones (neg + pos) as a DESIGN render-only proof — NOT a benchmark result — so the share-card atmosphere (deep-purple LENS_CORE centre, win-only cyan corona, darkened gradients) can be eyeballed in one pass. neg uses a real run's amber regression card (purple core, no corona); pos is a SYNTHETIC fixture built only to exercise the renderer's win branch (purple core + cyan corona) — its number is fabricated, never published. Delegates to the shared preview_...

Drive the REAL claude binary through clawback's PTY channel at a scripted inter-turn gap schedule — the faithful load arm. Because the bytes on the wire are produced by genuine Claude Code, this is the only driver that exercises the 1h-TTL nested-cache-control rewrite (arm A2) authentically. Use for headline/moat numbers and to cross-check the HTTP replay arm (.skills/replay). Requires node-pty and a running clawback proxy.

Turn a benchmark turn-log (or an already-analyzed run dir) into a report the GUI shows right away — runs analyze + plot so summary.json + report.csv AND charts/tokens_saved.svg + charts/tokens_saved.bg.svg all exist. The bare .bg.svg is the share-card PNG background; without it the downloaded/posted card has no chart lines. Also backfills old runs (--all) that predate the .bg.svg output. Use after a manual analyze, or to repair runs whose share PNG renders as a solid card. Pass --card to also...

Answer the load-bearing question "does clawback SESSION-KEY fragmentation actually cost Anthropic tokens?" from a finished run's per-instance turn-logs — zero new tokens. The prefix-fragmentation count (distinct SESSION KEYs per systemStableKey) tells you the cch rotation fragmented clawback's view; it does NOT tell you whether Anthropic cold-started. This does: it filters to REAL turns (mode=hash, drops keep-alive pings), partitions them into FRESH-key (sessionKey rotated vs the previous tur...

Statically inspect prompt-cache breakpoints in a captured /v1/messages body or a clawback --state file, with ZERO token spend and no API calls. Answers "where are the cache_control breakpoints, and which ephemeral tokens (cch / date / <env>) sit inside which cached prefixes?" — i.e. what a single mutation cold-starts. Use it to SEE why strip-ephemeral matters (cch precedes the earliest breakpoint, so it cold-starts every cached prefix every request) before spending tokens on a dynamic probe. ...

Run the clawback proxy and watch its log output for errors. Starts the bare proxy (honoring config layering), captures combined stdout+stderr to a log file, and follows it with warn/error/4xx/5xx lines highlighted. Supports foreground follow, background --detach (with --stop/--status), and --attach to tail an already-running proxy's log. Use when you want to launch clawback and monitor it for errors/regressions, or smoke-watch it after a change.

Watch an already-detached clawback proxy as an event stream — surface only actionable log lines (error/warn/4xx/5xx/crash signatures, plus rebind and runtime-mode toggles) AND announce a loud "PROXY DOWN" line the instant the proxy pid dies. Fills the gap that run_monitor.sh --attach leaves: a bare tail goes SILENT on a crash (BSD tail has no --pid), so silence reads as healthy-idle. Use when acting as the operator agent keeping the server alive — point an agent's Monitor tool at it (persiste...

Paired shadow-capture — one real claude session that captures the no-clawback baseline AND applies the armed knobs at the same time. This is the "shadow mode" knob for baseline capture: instead of forfeiting the optimizations for the measurement window (a plain passthrough baseline), the tee fans every turn to TWO unmodified clawback instances — PRIMARY (armed, default A5, streamed back to claude) and SHADOW (A0 passthrough, consumed for usage then discarded). Because both arms bill the SAME ...

Render the tokens-saved chart from an analyzer output directory. Dependency-free SVG generator — reads summary.json + report.csv produced by benchmark/bin/analyze.js and emits TWO SVGs of the same cumulative billable-input story (passthrough baseline vs clawback, honest green/red shaded gap): tokens_saved.svg (labeled, titled "Token Efficiency", for on-screen) and tokens_saved.bg.svg (BARE 1200×630, lines + wedge only, no text — the share-card PNG background; without it the posted card has no...

Compose a finished run's social SHARE CARD (the chart background + dark scrim + hero headline) and rasterize it to PNG so it can be eyeballed without opening the report GUI in a browser. Use it to check the thing the GUI's client-side PNG actually ships — most importantly, whether the chart lines survive the translucent scrim (a scrim dark enough for the light headline can crush the dark chart lines below the WCAG 1.4.11 3:1 floor, which renders as a near-blank card). Reads a run's summary.js...

Drive a reproducible HTTP replay load against a running clawback proxy. Replays one captured /v1/messages fixture at a load profile's inter-turn gap schedule, with built-in carry-over control (fresh path-mode session id + per-block cache nonce). Auth is an OAuth bearer (CLAWBACK_OAUTH_TOKEN), never an Anthropic API key; pre-flights the proxy and bearer before spending tokens. Use to generate clean, per-knob, deterministic-timing traffic for the analyzer; pair with .skills/drive (the faithful ...

End-to-end smoke test for the /<admin-path>/report saved-run viewer. Boots the real clawback binary against the repo's runs/ dir and curls every report route, asserting status + content, prefix mutability, public-read exemption, and that sensitive run-dir siblings stay unreachable. Use after touching src/report.js, src/report_ui/*, or the admin/report wiring.

Restart the detached clawback proxy and reconnect its monitor. Stops the proxy previously started with run_monitor.sh --detach (if any), then starts a fresh one in the background; the run log is recreated in place so a tail -F follower (run_monitor.sh --attach, or an agent's Monitor tool) re-attaches automatically. Honors the same --log-file/--pid-file options and `--` passthrough as run_monitor.sh. Use after a config or code change to cycle the proxy without disrupting the monitor. Pass --wa...

Shut down the clawback proxy stack. By default stops ONLY the detached proxy started via run_monitor.sh --detach (graceful SIGTERM, then SIGKILL after ~5s) and removes its pidfile, letting the monitor go quiet — interactive `clawback claude` sessions are left running on purpose. Pass --sessions for a full teardown that also SIGTERMs every clawback claude wrapper, listing each before signaling. Use to cleanly stop the proxy, or to tear the whole stack down.

Run the clawback end-to-end smoke test. Starts a mock upstream, spawns the proxy against it, exercises path-mode and hash-mode requests, walks the admin API, and prints the persisted state. Use when verifying the proxy still works after changes.

Cheaply prove the PTY turn-submission mechanism actually lands turns BEFORE any timed or headline run spends real tokens. Runs .skills/submit-smoke/scripts/submit_smoke.sh — one tiny passthrough Haiku block — and checks two independent signals: the driver's own "confirmed N/M" tally AND the count of real (non-ping) records the proxy logged. PASS only when every turn confirmed and the proxy logged at least that many real turns. Also reports which Enter encoding won (pure \r vs an escalated \n ...

Answer the research question "does a keep-alive ping that itself gets 429'd still refresh the prompt-cache TTL on Anthropic's side?" from captured turn-logs. A 429'd ping has no usage body, so its effect is only visible through the NEXT successful request on the same SESSION KEY. Runs .skills/ttl-429/scripts/ttl_429.mjs over one or more instance.*.ndjson turn-logs and classifies every 429'd ping as REFRESH (warm probe across the TTL boundary, no masking 200), NO-REFRESH (cold probe), or INCON...

Config doctor for clawback — loads the merged config (DEFAULTS < global < ./CLAWBACK.md < CLI overrides) exactly as the proxy's loadConfig does, prints a secret-free summary of the resolved values plus the merge-order sources, and exits non-zero if the canonical CLAWBACK.md did NOT take effect (host not 0.0.0.0, tls off, or adminToken missing) so a bad parse fails loudly instead of silently falling back to loopback defaults. Read-only; never prints the adminToken value, only its length. Use t...

Quiet operator watch for a detached clawback proxy — stream ONLY legitimate errors and never the benign flood. Wakes on [error]/[fatal] lines, crash signatures (uncaught/EADDRINUSE/ECONN*/Error:/self-loop), server-side 5xx that are NOT the transient 529, real (non-keep-alive) request failures, and a loud "PROXY DOWN" the instant the pid dies (then exits non-zero). Deliberately silences keep-alive ping failures (401 auth-stale / 404 retired-model / 429/529), real-request 429+529 (Claude Code a...

Emit-on-event health watcher for a long paired/ab benchmark run, meant to be fed to the Monitor tool (each stdout line becomes one notification) so an unattended 75-min run cannot fail silently. Coverage-first by design — it speaks up on liveness (ALIVE), on new error signatures in the proxy/tee logs (ERROR), on a stall or crash (STALL/DEAD — silence is not success), and on completion (COMPLETE) — not just the happy path. Stall is tracked on the SHADOW (A0) turn-log, which is passthrough with...

Generate or refresh the canonical CLAWBACK.md config. The front matter is built from the live DEFAULTS export in src/config.js (so it can never drift as options are added), with the only forced deviations being the two a LAN-reachable bind needs — host=0.0.0.0 and tls=true. adminToken is left as a null placeholder for you to set (it no longer mints one); a real existing token, or an explicit CLAWBACK_CANONICAL_TOKEN, is PRESERVED, and a token's value is NEVER printed (only presence and length...