Loaded through the root pi-ext package; requires nu on PATH.
pi --nushell enables both tools at session start and hides active bash and powershell from the model.
/nushell toggles the same tools during a session.
/nushell on, /nushell off, and /nushell reset are explicit alternatives.
/nushell reset discards the persistent worker's state without changing active tools.
Turning the tools off restores only the shell tools displaced by this toggle.
Pi's ! and !! remain owned by nu-bang.
nu: fresh nu --no-config-file --no-history --error-style fancy --table-mode markdown -c process per call, streaming output and optional timeout.
nu_session: persistent native Nu MCP worker, serialized calls, state scoped to the active Pi session, reset on session navigation, toggle-off, or shutdown.
Use nu unless a later call requires variables, functions, imports, environment changes, or cwd set by an earlier nu_session call.
Both tools use Nushell syntax, not Bash or PowerShell.
Nu's native commands handle structured data; ^name explicitly runs an external executable.
Use help <command> for installed Nu guidance.
MCP evaluates expressions and returns NUON with output and history_index.
print writes to the worker's stderr, which also carries verbose Nu protocol diagnostics and is discarded; return an expression instead.
MCP does not treat a nonzero external exit code as an evaluation error: use ^command | complete and inspect exit_code.
MCP collects output rather than streaming it, and replaces responses over its default 10 KB limit with a history reference.
Each persistent request has a 110-second client deadline; interruption resets worker state, but detached external processes may continue running.
Reset does not roll back filesystem changes.
Set nushell.enable in Pi's settings.json to activate both tools at session start:
{
"nushell": { "enable": true }
}
Disabled by default.
Precedence: --nushell, then PI_NUSHELL_ENABLE (true|false|1|0), then trusted project settings, then user settings.
Untrusted project settings are ignored.
An invalid value from the highest present source leaves the tools unchanged with a warning; lower sources are not consulted.
/nushell off still disables them for the current session.
Set PI_NUSHELL_DEBUG=1 to enable private JSONL diagnostics or PI_NUSHELL_DEBUG=0 to override global debug selection.
Global user settings support "pi-ext": { "debug": true | "nushell" | ["nushell"] }.
See debug contract for file locations, privacy, cap, and selection rules.
Safe events include lifecycle, tool selection, process lifecycle, span durations, byte counts, and allowlisted status classifications.
fresh, session.connect, and session.request spans use matching spanId start and terminal events with durationMs.
Fresh terminals classify status; session-request errors classify kind.
Logs never contain Nushell source, output content, environment values, raw errors, or arbitrary data.
mise run //extensions/nushell:e2e-json runs five isolated module exercises plus a persistent-state probe via Pi print JSON mode with --no-session; it retains prompts, JSON events, debug logs, outputs, and analyses under the private OS temporary directory pi-ext-nushell-json/.
mise run //extensions/nushell:bench reports fresh, cold persistent, and warm persistent end-to-end tool latency in benchstat format.
It uses the real Pi extension harness and Nu binary, warms each path, and alternates fresh and warm call order each round.
MCP schemas load with the first persistent worker rather than at inert extension startup.
On Linux (Node 26.9.0, Pi 0.87.1, Nu 0.115.1), //:extension-startup-bench measured RPC readiness falling from 478 ms ±7% to 449 ms ±7% (25 runs each; benchstat p=0.003).
The Nu call benchmark showed no significant fresh, cold-worker, or warm-worker latency changes (20 runs each); this preserves the warm-call advantage without eagerly loading MCP at startup.
# nushell
Opt-in Nushell tools for Pi.
Loaded through the root pi-ext package; requires `nu` on `PATH`.
`pi --nushell` enables both tools at session start and hides active `bash` and `powershell` from the model.
`/nushell` toggles the same tools during a session.
`/nushell on`, `/nushell off`, and `/nushell reset` are explicit alternatives.
`/nushell reset` discards the persistent worker's state without changing active tools.
Turning the tools off restores only the shell tools displaced by this toggle.
Pi's `!` and `!!` remain owned by `nu-bang`.
- `nu`: fresh `nu --no-config-file --no-history --error-style fancy --table-mode markdown -c` process per call, streaming output and optional timeout.
- `nu_session`: persistent native Nu MCP worker, serialized calls, state scoped to the active Pi session, reset on session navigation, toggle-off, or shutdown.
Use `nu` unless a later call requires variables, functions, imports, environment changes, or cwd set by an earlier `nu_session` call.
Both tools use Nushell syntax, not Bash or PowerShell.
Nu's native commands handle structured data; `^name` explicitly runs an external executable.
Use `help <command>` for installed Nu guidance.
MCP evaluates expressions and returns NUON with `output` and `history_index`.
`print` writes to the worker's stderr, which also carries verbose Nu protocol diagnostics and is discarded; return an expression instead.
MCP does not treat a nonzero external exit code as an evaluation error: use `^command | complete` and inspect `exit_code`.
MCP collects output rather than streaming it, and replaces responses over its default 10 KB limit with a history reference.
Each persistent request has a 110-second client deadline; interruption resets worker state, but detached external processes may continue running.
Reset does not roll back filesystem changes.
Set `nushell.enable` in Pi's `settings.json` to activate both tools at session start:
```json
{
"nushell": { "enable": true }
}
```
Disabled by default.
Precedence: `--nushell`, then `PI_NUSHELL_ENABLE` (`true|false|1|0`), then trusted project settings, then user settings.
Untrusted project settings are ignored.
An invalid value from the highest present source leaves the tools unchanged with a warning; lower sources are not consulted.
`/nushell off` still disables them for the current session.
Set `PI_NUSHELL_DEBUG=1` to enable private JSONL diagnostics or `PI_NUSHELL_DEBUG=0` to override global debug selection.
Global user settings support `"pi-ext": { "debug": true | "nushell" | ["nushell"] }`.
See [debug contract](../DEBUG.md) for file locations, privacy, cap, and selection rules.
Safe events include lifecycle, tool selection, process lifecycle, span durations, byte counts, and allowlisted status classifications.
`fresh`, `session.connect`, and `session.request` spans use matching `spanId` start and terminal events with `durationMs`.
Fresh terminals classify `status`; session-request errors classify `kind`.
Logs never contain Nushell source, output content, environment values, raw errors, or arbitrary data.
`mise run //extensions/nushell:e2e-json` runs five isolated module exercises plus a persistent-state probe via Pi print JSON mode with `--no-session`; it retains prompts, JSON events, debug logs, outputs, and analyses under the private OS temporary directory `pi-ext-nushell-json/`.
`mise run //extensions/nushell:bench` reports fresh, cold persistent, and warm persistent end-to-end tool latency in benchstat format.
It uses the real Pi extension harness and Nu binary, warms each path, and alternates fresh and warm call order each round.
MCP schemas load with the first persistent worker rather than at inert extension startup.
On Linux (Node 26.9.0, Pi 0.87.1, Nu 0.115.1), `//:extension-startup-bench` measured RPC readiness falling from 478 ms ±7% to 449 ms ±7% (25 runs each; benchstat p=0.003).
The Nu call benchmark showed no significant fresh, cold-worker, or warm-worker latency changes (20 runs each); this preserves the warm-call advantage without eagerly loading MCP at startup.