Documentation
¶
Overview ¶
Package nudge is the proactive half of the agent-hint subsystem: when an agent runs a legacy tool that has a better agentic counterpart, it emits ONE rate-limited hint pointing at it — never changing the tool's behavior.
It lives in coreutils (not a single product) so every shell that installs the coreutils in-process userland — bashy AND ycode and any other consumer — gets the same steering toward the composable structured verbs (grep --agentic, ast refs/symbols/map). A traditional shell (zsh) cannot do this; a hint at the exec-audit chokepoint is the elevator from "the tool exists" to "the agent uses it".
Invariants: help, don't obstruct. Hints are stderr-only (stdout stays pure data), rate-limited to once per tool per process, and fully silenceable. They are observers on interp.WithAuditHandler — they never block or alter a command.
Index ¶
Constants ¶
const SchemaVersion = "bashy-hint-v1"
SchemaVersion is the agent-facing hint wire schema. It is the established contract agents already parse; keep it stable.
Variables ¶
This section is empty.
Functions ¶
func Enabled ¶
func Enabled() bool
Enabled reports whether proactive hints should fire. BASHY_AGENTIC off is the master kill; otherwise BASHY_HINTS is the explicit control (off-ish silences, on-ish forces on); unset defaults to agent-driven mode only.
func OnFailure ¶
OnFailure emits at most one structured hint for a failed invocation. It is the error-path counterpart to Nudger.OnAudit and uses the same schema and BASHY_HINTS gate. env is the invoking tool's environment, not the host process environment.
func Suggest ¶
Suggest returns the hint text for a command (args[0] is the tool name), or "" when there's nothing to suggest. Pure (argv in, text out) so callers share the rule set.
func SuggestFailure ¶
SuggestFailure returns a hint for a command-line idiom that commonly crosses from BSD userlands into GNU tools, or "" when the argv is not recognized. Callers must invoke it only after the command has failed: valid GNU commands are never annotated, and the arguments are never rewritten.
Types ¶
type Nudger ¶
type Nudger struct {
// contains filtered or unexported fields
}
Nudger emits proactive tool-hints, rate-limited to once per tool for the life of the process (a shell session).
func Default ¶
func Default() *Nudger
Default returns a process-singleton Nudger on os.Stderr, so rate-limiting (once per tool) holds across every command in a session even when each is run on its own interp.Runner.
func (*Nudger) OnAudit ¶
func (n *Nudger) OnAudit(ev interp.AuditEvent)
OnAudit is the interp.WithAuditHandler callback. It fires once per simple command (post-expansion); it acts only on watched tools, once per tool per process, and only when hints are Enabled.
Source Files