Appearance
Nushell
The nushell stack pack. Nushell's whole point is that a pipeline carries records, not text, so ls | where size > 1mb | get name beats shelling out and parsing lines by hand – but an agent reaching for grep or awk or a hand-rolled path string is really writing bash in a .nu file. This module is one PostToolUse gate that catches those tells on every .nu write and feeds the nu-native fix straight back, so the correction lands inside the same edit loop instead of in review. It nudges, it never blocks anything but a nushell smell.
In Practice
The gate runs after the edit, not before it. On a clean file it says nothing; on a smell it exits 2 with the fixes on stderr, and Claude Code reads that and rewrites the line before moving on.
Write bash-in-a-nu-file and the gate catches it. The agent saves a .nu script with a line that both shells out to grep and caps an external command's output on its first run:
nu
let hits = (^rg "todo" src | ^grep -v test | first 20)That single line trips two checks at once – the external text tool and the first-run cap – so nu-lint.nu exits 2 and prints, verbatim:
nu-lint, .claude/scripts/scan.nu has nushell-idiom smells, prefer structured data over string munging:
line 4, external text tool, use a nu native (where / str replace / split / parse) not grep/sed/awk
line 4, capping an external commands output with first/last/take, on a first run dont cap, capture it then slice (the nu mcp rule)
see .claude/memory/lessons/nu.md for the idioms if the memory part is installedRewrite to a structured pipeline and the gate goes quiet. Claude Code reads those fixes and drops the grep for a where and the cap for nothing at all:
nu
let hits = (^rg "todo" src | lines | where $it !~ "test")On the next save the gate re-fires, finds no smell at a command position, and exits 0 with nothing on stderr.
An example outcome. The committed .nu file carries a records-through-where pipeline rather than shelled-out text munging, and the correction happened agent-to-gate inside one edit loop, no human in the middle and no separate lint pass to remember to run.
The Checks
All six are pure string and regex matches on the raw file – the gate can't parse nushell, so it takes the high-signal tells and accepts the odd false positive, the same bargain the style linter makes. Every check is anchored to a command position (line start or straight after a pipe), and comment and blank lines are skipped first, so a grep named inside a comment or a string literal never trips it.
| Check | What trips it at a command position | The nu-native fix it nudges toward |
|---|---|---|
| External text tools | grep, sed, awk, cut, tr (bare or ^-prefixed) | where, str replace, split, parse |
| head / tail | head or tail as unix slicers | first / last – and don't cap a first-run pipeline at all |
| Capping external output | ^cmd ... | first/last/take N on a first run | Capture the result, then slice the saved value (the nu mcp rule) |
| String-concat paths | $"($a)/($b)" or + "/" | path join, so separators and platform are handled |
| echo for output | echo at line start or after a pipe | print, since echo streams a value into the pipeline |
| each for one column | `each { | f |
The gate stops collecting after 10 findings, reports what it has, and always points the message at .claude/memory/lessons/nu.md for the idioms behind the nudge.
The Deliberate Choices
Each of these is flagged in the source so the trade-off is easy to change.
- It fails open. Any internal error – an unreadable payload, a broken read – degrades to exit 0, exactly like the style linter, so a bug in the guard can never block an edit. Only a genuine nushell smell exits 2.
- String checks only, no semantics. It cannot parse nushell, so it reads the tells and lives with the occasional false positive rather than pretending to understand the code. New checks get added as real smells surface.
- It respects
HARNESS_HOOKS_OFF. When that flag is1– set by a harness hook that spawned Claude up the chain – the gate no-ops immediately, so it never re-fires down a recursion. - It points at the lesson slice but doesn't require it. The message names
.claude/memory/lessons/nu.md; if the memory part isn't installed the hint is just harmless text, and the gate works regardless.
Key Files
nu-lint.nu
The gate – a PostToolUse hook that reads the tool payload from stdin, and short-circuits to exit 0 unless the edited file actually exists and ends in .nu. It walks the file line by line, skipping comments and blanks, runs the six command-position checks, and on any hit exits 2 with a per-line fix on stderr so Claude Code feeds it straight back. Clean or unreadable exits 0, and the whole body is wrapped so any internal error fails open.
settings-fragment.json
The wiring – the single PostToolUse entry you merge into a project's .claude/settings.json by hand, matching Edit|Write|MultiEdit and running nu .claude/stack/nushell/nu-lint.nu. If the hooks pack is also installed, this entry sits alongside its style-lint entry and Claude Code runs both on every matching edit.
README.md
The pack notes – what the gate does and why, the six checks in prose, the deliberate choices, and how to install: harness-install --parts nushell copies the gate to .claude/stack/nushell/, then you merge the fragment by hand. It also carries the one-line snippet to paste into the target CLAUDE.md so the agent reads the nu idioms before it writes and cooperates with the gate rather than fighting it.
Connects to
- Registers its own PostToolUse gate that sits beside the hooks pack's style-lint – Claude Code runs every matching hook, it shares the pack's
HARNESS_HOOKS_OFFrecursion guard, and it copies the pack's fail-open stance so a broken guard never blocks an edit. - Points every fix message at memory –
.claude/memory/lessons/nu.mdis the nu lesson slice, the why behind each nudge, and the CLAUDE.md snippet tells the agent to read it before writing nushell. The gate is the wall, the lesson slice is the reason, and neither hard-requires the other. - Placed by the installer with
harness-install --parts nushell, which copies the gate into.claude/stack/nushell/, leaving the settings merge as the one manual step.