👉 Nudgeist [Claude Code Plugin - Hooks - Node.js - Benchmarking]

Ivan Luna 14 Oct, 2026 05 Mins read
👉 Nudgeist [Claude Code Plugin - Hooks - Node.js - Benchmarking]

Nudgeist gets a second opinion before a message reaches an expensive model. It asks Haiku whether a cheaper model or a lower effort will do and, when that switch pays once the prompt cache is counted, holds the message once with that suggestion. A nudge, not a switch: it’s not a router, a proxy or a model switcher, and it never switches anything itself. You decide. No server, no telemetry, MIT.

In active development: this is the project I’m working on right now.

View on GitHub Documentation

One model for every message:


A Claude Code session runs every message on the model and effort it was set to, so a typo fix gets the same model as a redesign. Switching by hand means guessing, and the guess can backfire: a model you haven’t used in this session has to read the whole conversation from scratch, while your current model reads it from the prompt cache at a fraction of its usual price. So a lighter model isn’t always cheaper for that turn.

Nudgeist asks the question for you, does the cache arithmetic, and only speaks up when the answer is worth it.

How it decides:


  • What you’re running. It reads the model, effort and context size of your last turn from the session transcript, and Claude Code tells it about /model as it happens.
  • Whether anything can be saved. If nothing cheaper could pay, it skips the check: no wait, no cost.
  • A second opinion. Haiku reads your message plus a short brief: the session title, the project folder’s name, your last requests, the end of Claude’s last reply, the files in play with their sizes, and the size of the conversation. It never opens your files.
  • Whether switching pays. It does the cache arithmetic with list prices and the cache lifetime your session actually uses, and suggests a model only when it at least halves the turn’s cost. When it doesn’t, it may suggest a lower effort instead.
  • One question, then quiet. It holds a message once. Keep your model twice in a row and it stays quiet for the rest of the session.

You decide:


The notice quotes your message back, so nothing is lost. Send it again unchanged to keep your model, or put a command in front to run that one message lighter. Either way, your next message runs on the model and effort you chose for the session. After the first turn on a 5.5 model, a notice suggesting a lighter model also shows the estimated cost of both options.

  • /nudgeist:haiku <message> runs this one message on Haiku.
  • /nudgeist:sonnet <message> runs it on Sonnet.
  • /nudgeist:low <message> and /nudgeist:medium <message> run it on your model at a lower effort.
  • /nudgeist:check <message> asks Haiku which of these fits, without doing the work.

It stays out of the way of commands, claude -p, SDK and background sessions, which are never held. Any error, timeout or unclear verdict lets the message through, and NUDGEIST=off turns it off.

What it costs:


Each checked message costs one Haiku call: about 1,200 tokens and usually about 2 seconds (median 1.9 s; 27 of 36 calls took 1.5 to 3 s, 2 took over 8 s), measured on Claude Code 2.1.296. Messages with nothing to save aren’t checked, and a call that takes longer than 8 seconds lets your message through without a notice.

The cost figures in a notice use list prices for the 5.5 models. On a subscription you pay a plan, not per token, so they are a rough guide.

Checked, not assumed:


The repository ships a bench of twelve coding tasks graded by hidden tests, solved on Haiku and Opus, with every raw run, diff and advisor call published and hashed. On 2026-10-13, Haiku 5.5 passed all twelve. Of 36 advisor calls, 16 suggested Haiku and 20 held back; none suggested Haiku where it failed.

The limits are published with the results. Since Haiku never failed, the costly mistake (suggesting Haiku where it fails) is still untested, and harder tasks are needed for that. The tasks are my own and the samples are small, so the numbers are a signal, not proof. Those runs used an earlier version of the session brief, and effort suggestions aren’t graded.

Two editions:


  • Full edition (the repository): the hooks that look at each message before it’s sent, plus the five commands.
  • Commands edition: Anthropic’s plugin directory accepts background hooks only from Verified organizations, so the edition submitted there has the five commands only, with no hooks and no code.

Install:


# Claude Code, full edition
/plugin marketplace add nudgeist/nudgeist
/plugin install nudgeist@nudgeist

# Use
/nudgeist:check rename the config loader  # which model or effort fits, without doing the work
/nudgeist:haiku fix the typo in README    # run this one message on Haiku

It needs Node.js 18 or later: the hooks run with node.

Technical Stack:


  • Runtime: Node.js 18+, ESM, no dependencies. The hooks are local scripts that read the session transcript and return a decision.
  • Claude Code integration:
    • three hook events: SessionStart and PostModelSwitch to track the session’s model, and UserPromptSubmit to look at each message before it’s sent;
    • bounded reads of the session transcript;
    • five user-invoked commands.
  • Cost model: list prices, cache reads versus a fresh read of the whole conversation, and the cache lifetime the session uses.
  • Tests: npm test covers the session reader, the cost arithmetic, the advisor’s reply parser and the hold-once logic.
  • Bench: hidden tests, published raw runs, diffs and advisor calls, hashed.
  • Privacy:
    • no server and no telemetry;
    • the second opinion runs through your own Claude Code and goes wherever Claude Code normally sends your messages: Anthropic, or your gateway or cloud provider;
    • the state file keeps a hash of the held message, never its text. Details in the privacy policy.

Conclusion:


Nudgeist was built in October 2026 around one question: can a fast model tell, before the work starts, when an expensive one isn’t needed? The project demonstrates:

  • Building against the real cost model of an agent session: a model switch is only worth it once the prompt cache is counted.
  • Keeping the human in charge: it asks once, then gets out of the way, and never switches anything itself.
  • Using the Claude Code hook API with a fail-open design: any error, timeout or unclear verdict lets the message through.
  • Measuring with discipline: a bench graded by hidden tests, every raw run published and hashed, and the limits stated next to the results.
  • Respecting privacy by design: no server, no telemetry, and nothing kept of the message but a hash.



Related projects

All projects