pix-nudge

Pi extension — model-steering nudges (tools + capability).

What it does

Registers three nudge hooks. Each names only the relevant tool, not a full inventory, and none blocks a call. Every nudge shows in the transcript as the same collapsed one-line card (⚠ nudge <summary> · <kind>); the expand toggle shows the full text.

Tools nudge — catches bash calls that reimplement a first-class tool (read, ls, grep, find, edit), including sed -n '10,40p' reads, stand-ins with only a trailing | head/| tail, and commands that pix-optimizer has prefixed with rtk:

• Appends one [pix-nudge] line to that bash result on the first use of a command category, then on every 5th use (the model reads tool results, not UI notices), plus a nudge card for the user. The line names the tool options that replace the shell idiom (for example read offset/limit).
• Deferred targets load automatically. When the named tool is deferred, the nudge activates it (the way tool_search would), says so in the line, and marks the card (loaded). The model can call it next without a discovery round-trip.
• The command still runs — it teaches, doesn't block (early blocking wasted a turn on forced retry). Calls in that category between reminders are silent.
• Three whole-command patterns too: a backgrounded process (&, nohup, setsid) points at proc; a heredoc or python - << script that writes a file (not /tmp) points at write/edit, so the change shows as a diff; any other standalone python -c / python - << snippet points at python_run (piped … | python -c stays in bash).
• On Windows, a bash call that matches no other rule gets a nudge toward the powershell tool, on the same first-then-every-5th cadence. Bash stays enabled.
• Only installed tools are named. A nudge is skipped when its tool is not registered this session, or when it is deferred and tool_search is missing (it could not be loaded). A hint that names a missing tool (or \edit``) is dropped and the nudge stays. If the host cannot list its tools, no tool nudge fires.
• Bash stays available for everything else (pipes, compound commands, real shell work).

The tools nudge also watches two native tools, once per session each:

• A read without offset of a source file with 300+ lines points at ast action outline, then action symbol for one function.
• A grep whose pattern is one code identifier (camelCase, PascalCase, snake_case, or SCREAMING_CASE) points at graph action:"impact" or lsp action navigate references. Plain words and regexes stay ordinary greps.

Nudge steers; it does not guard. Privileged auth stand-ins (bash sudo/ssh) are not nudged here — those are hard-blocked and redirected to sudo_run/ssh_run by pix-gate, which handles the auth safely. Guarding (stop) and steering (teach) are separate concerns in separate packages.

Capability nudge — steers the model toward tool discovery over guessing:

• One-time orientation message on the first prompt: tool counts, the deferred-tool note, deferred non-MCP tool names grouped by prefix family (for example agent_{agent,control}), and a capability → tool map that lists only the tools registered in this session (ask_user, read_skills(), context7, web, lsp, mcp).
• A one-line reminder every 10 turns pointing at read_skills(), tool_search and MCP, each only when registered. The orientation's deferred-tools line also needs tool_search.
• When .pi/graph/graph.json exists and the graph tool is registered, both messages also route codebase questions to graph(action:"query").
• Delivered as visible custom messages, not system-prompt rewrites, so the cached prompt prefix stays intact.

Loop nudge — catches a doom loop: the same tool, arguments and result 3 times in a row, or the same cycle of up to 5 calls (A→B→A→B…) repeated 3 times. A failing call counts by tool and first error line, so the same error with tweaked arguments also counts. Appends one [pix-nudge] line to the third result plus a nudge card. A changed result resets the streak, so re-running tests after an edit is not a loop.

Install

pi install npm:@xynogen/pix-nudge

Bundled in @xynogen/pix-core. Install it alone only if you do not use pix-core.

Full distro

This package is part of Pix. The installer sets up Pi and the full distro. See Install for the notes for each OS.

# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/xynogen/pix-mono/main/scripts/install.sh | sh

# Windows
irm https://raw.githubusercontent.com/xynogen/pix-mono/main/scripts/install.ps1 | iex

License

MIT