Level 300 · Advanced

Advanced and custom

For users who want to bend the tool to their workflow: custom scorers, CI integration, hook tuning, and shipping audit data downstream.

By Level 300 you’re not just using TokenSquirrel — you’re shaping it. Custom scorers, tuned thresholds, automated audits, downstream pipelines.

Background reading. The team-governance and observability stack arguments in Part 3: Scaling the Discipline are the natural pairing for this level — the JSONL pipeline below is the lightweight version of the Datadog/Honeycomb/LiteLLM/Bifrost discussion there.

1. Add a scorer for your team’s pet metric

The situation: your team cares about something the default 15 scorers don’t measure. Maybe it’s “how often did we use a specific in-house slash command.” Maybe it’s “how much of our spend went on documents we pasted as images.”

What to do:

  1. Open tools/tokensquirrel/src/scoring/scorer.ts.
  2. Add a function that takes the parsed history/stats/settings and returns a ScoreResult.
  3. Use ratioToScore (more is better) or inverseScore (less is better) from scoring/benchmarks.ts so your grade thresholds match the rest.
  4. Append the function call to runAllScorers().
  5. Add a narrative case in output/narratives.ts so the headline can phrase your scorer’s output as a sentence.

The terminal and markdown formatters pick it up automatically — no formatter changes.

How to verify: npm run dev claude --detail shows your scorer with the others.

2. Run audits in CI for your whole team

The situation: you want a weekly, automatic snapshot of how every dev on the team is using Claude Code, without anyone having to remember to run a command.

What to do: the history file (~/.tokensquirrel/history.jsonl) is the integration point. Append-only JSONL, schema in src/types.ts. Each developer commits a script that:

  1. Runs npx tokensquirrel claude --format md --label "weekly-$(date +%Y-%V)" and saves the output.
  2. Pipes the JSONL line to a shared location (S3, a database, a Slack webhook).

A GitHub Action with cron 0 17 * * FRI runs it every Friday afternoon. The team-level dashboard becomes whatever you build over those JSONL rows.

Privacy note: the JSONL contains scores and metadata, not transcripts. But the --label field is freeform, so don’t put project names in there if your team treats those as sensitive.

3. Tune your hooks instead of stacking them

The score this fixes: hook injection load, SessionStart noise.

The situation: you have a UserPromptSubmit hook that injects context, a SessionStart hook that loads team config, another that prints a banner, another that logs to a file. Each one fires every prompt or session start, and each one adds tokens.

What to do:

  1. Run npx tokensquirrel claude mot and look at the hook injection load + SessionStart noise lines.
  2. Open ~/.claude/settings.json and the project’s .claude/settings.json.
  3. For each hook, ask: does this need to be a hook, or could it be a one-off command I run when I actually need it?
  4. Hooks that print banners are the first to go. Logging hooks can usually be replaced by tokensquirrel claude itself, which already reads the same data.
  5. Combine related hooks into a single script when you can — the cost is the number of hooks, not what each one does.

How to verify: both setup-weight scores rise, and your sessions start faster.

4. Build a custom skill that scaffolds your audit habit

The situation: you keep forgetting to run the weekly MOT.

What to do: write a personal skill at ~/.claude/skills/weekly-mot/SKILL.md that triggers when you say “weekly check.” The skill body just runs the audit and writes the markdown to your notes.

---
name: weekly-mot
description: Run the TokenSquirrel weekly MOT and save it to ~/notes/. Use when the user says "weekly check", "Friday MOT", or it's the end of a working week.
---

Run:

```bash
npx tokensquirrel claude mot --format md > ~/notes/squirrel-$(date +%Y-%V).md

Then summarise the top 3 grades and the headline cost in 2 sentences.


**How to verify:** typing "weekly check" on a Friday triggers the skill. The skill bloat score doesn't suffer because you actually use this one.

## 5. Ship audit data to a dashboard or Slack

**The situation:** you want a visible feedback loop. Score in a dashboard, weekly headline in #engineering.

**What to do:** the dashboard is already built — `npx tokensquirrel claude --dashboard` runs a local web UI. To ship to Slack, write a tiny script over the JSONL:

```bash
# weekly-slack.sh
LATEST=$(npx tokensquirrel claude --format md)
curl -X POST -H 'Content-Type: application/json' \
  --data "{\"text\": $(printf '%s' "$LATEST" | jq -Rs .)}" \
  "$SLACK_WEBHOOK_URL"

Run it from cron, a launchd plist, or a CI scheduled job.

For something fancier — trends, per-developer breakdowns, model split — read ~/.tokensquirrel/history.jsonl directly and feed it into whatever you already use for metrics. It’s append-only JSONL with a stable schema; you can build on it without worrying about migrations.

Contribute back

If a custom scorer turned out to be useful for your team, open a PR. The codebase is small (zero runtime deps), splits cleanly into parsers/scoring/output, and welcomes additions. Issues and “this default doesn’t reflect how I work” reports are equally welcome.