experimental-nudge

A Claude Code plugin that fires a brief consideration prompt as a system reminder after every PostToolBatch event (each agent loop iteration). The agent reads it, may engage, and proceeds. Pure salience. No gating. No enforcement.

Experimental

Not part of the regular Michi toolkit. Directionally positive evidence; not validated as a stand-alone intervention. See Caveats below.

What it does

After each iteration of the agent’s tool-call loop, the plugin injects a consideration prompt as a system reminder in the next model call:

Before your next step, consider:

• What are we doing? Why?
• What are the options? (Not just the one you’re pursuing.)
• What can we do vs what should we do?
• What do we know, what are we assuming, what might we be missing?
• Remember reuse over reinvention.
• Don’t assume. Verify if there is any doubt (for example, docs can be stale, incomplete, or wrong). And surface assumptions.
• Orient to the current discussion and local sources first — most recent user instructions, then session docs/prompts, then repo docs. If you can’t trace your reasoning to these — or if a source looks wrong, contradictory, or incongruent (including the user’s own instructions; even highest-authority sources have errors) — clarify before asserting. Outside knowledge is background, not authority.
• Appropriate action, for the context and given human guidance, is much more important than optimization or efficiency.
• It’s okay to slow down. A thoughtful decision is better than a rash one.

The agent treats the reminder as any other system reminder — read, may consider, may ignore. No action is forced.

What it doesn’t do

• Doesn’t gate any action. No PreToolUse blocks. The agent can always proceed.
• Doesn’t track state. No counter, no state file, no per-session memory.
• Doesn’t log. Errors go to stderr; success is silent.

What it doesn’t catch

The nudge fires between tool calls (PostToolBatch), not at user-prompt arrival. If the agent misreads the user’s question and proceeds with the wrong frame, this nudge alone won’t catch that — the user’s correction is still load-bearing for that class of failure.

Install

Clone the Michi repo and add the marketplace, then install:

git clone https://github.com/csepulv/michi.git
claude plugin marketplace add ./michi/toolkit
claude plugin install experimental-nudge@michi

Verify:

claude plugin list
# expect to see: experimental-nudge@michi (enabled)

The plugin is now active in every Claude Code session.

Disable per-project

In a project where you don’t want the nudge firing, add to that project’s .claude/settings.json:

{
  "enabledPlugins": {
    "experimental-nudge@michi": false
  }
}

Project-level settings override user-level for plugin enablement.

Disable globally

claude plugin disable experimental-nudge@michi

Or remove entirely:

claude plugin uninstall experimental-nudge@michi

Customization

The prompt content is currently hardcoded. There’s no userConfig or override mechanism in v0.1 — the bullets reflect Christian’s judgment vocabulary, drawn from Michi principles. To use different content, fork the plugin and edit hooks/checkpoint-nudge.js.

Why this exists

The plugin emerged from the Michi metacognition investigation: the observation that judgment in agent work is the cumulative effect of many small choices, not single big decisions. Periodic re-surfacing of a specific consideration sequence may bias those small choices toward more careful framing. The evidence is suggestive but not conclusive.

The author’s view: the salience nudge probably contributes to better judgment in concert with other discipline (sharp human correction, principled docs, structured skills), but is not sufficient on its own and not validated as a stand-alone intervention.

Caveats

• Small evidence base. A few A/B-shaped milestone pairs on one project, plus end-to-end observation across one nine-milestone epic. Single author, single agent calibration history.
• Likely insufficient alone. The strongest evidence supports a compound effect: Michi-style cumulative-judgment docs + sharp human correction at moments of failure + this nudge. Strip any of those three and the result may degrade. Installing the nudge into a project without the other two may add little value.
• May add noise. If the agent treats the reminder as wallpaper after several firings, it stops doing useful work. Not directly observed, not ruled out.
• Content is opinionated. Other operators may find the bullets generic, irrelevant, or wrong-shape.

If you try it and have observations — positive, negative, mixed — open an issue.

Where the source lives

toolkit/experimental/nudge/ in the public repo.

License

MIT.