gnhf CLI reference

This file is a cache, not the source of truth. Verify with gnhf --help before relying on a flag; the roster and options change between releases. Captured against gnhf v0.1.49.

Normally you should not call gnhf directly — use scripts\start-run.ps1, which adds the preflight checks and the guaranteed finalize step. This reference exists for reading the flags the wrapper passes and for diagnosing a run.

Install

The skill vendors its own copy — you should not need a global install:

npm install gnhf --prefix "$env:USERPROFILE\.scout\m-skills\lights-out\vendor"

That produces vendor\node_modules\gnhf\dist\cli.mjs, which the scripts run via node. Only node needs to be on PATH; the npm-generated gnhf / gnhf.cmd / gnhf.ps1 shims are irrelevant here (they are 28-line launchers that resolve paths relative to their own location, so they cannot be moved or copied anywhere useful).

Resolution order is $env:LIGHTS_OUT_GNHF → vendored → gnhf on PATH.

On this machine, registry.npmjs.org is TLS-intercepted and fails with ERR_SSL_SSL/TLS_ALERT_HANDSHAKE_FAILURE. Use the configured Microsoft proxy registry — that is the default, so a plain npm install works; do not pass --registry=https://registry.npmjs.org.

A global npm install -g gnhf still works as a fallback, but nothing in the skill requires it.

Flags

Flag	Notes
`--agent <agent>`	`claude`, `codex`, `rovodev`, `opencode`, `copilot`, `pi`, `cursor`, or `acp:<target-or-command>`
`--model <model>`	Overrides `agentModel.<agent>` from config
`--max-iterations <n>`	Abort after N iterations
`--max-tokens <n>`	Abort after N total input+output+cache tokens
`--max-rate-limit-wait <dur>`	Abort after this much cumulative usage-limit wait (`30m`, `2h`, `0`)
`--fallback-model <model>`	Retry a Claude usage-limit rejection with this model instead of waiting
`--stop-when <condition>`	Natural-language completion condition; survives resume. `""` clears it
`--prevent-sleep <on\|off>`	Keep the machine awake. Always `on` for overnight runs
`--worktree`	Run in a separate git worktree, enabling parallel runs on one repo
`--current-branch`	Commit on the current branch instead of creating `gnhf/<runId>`
`--push`	Push after each successful iteration
`--meteor-frequency <0-5>`	TUI meteors. The wrapper sets `0` (no TTY, so it is only log noise)
`--mock`	TUI demo only. Replays canned iterations, does no git work, does not exit. Never use it to validate a real run

Run identity

Deterministic, derived from the prompt — so a run is findable months later without guessing:

slug   = prompt.toLowerCase()
           .replace(/[^a-z0-9]+/g,'-')
           .replace(/^-+|-+$/g,'')
           .slice(0,20)
           .replace(/-+$/,'')
hash   = sha256(prompt).hex.slice(0,6)
runId  = "<slug>-<hash>"
branch = "gnhf/<runId>"

On collision gnhf appends -1, -2, …, so the predicted id may not be the final one. Resolve-LightsOutRunDir in scripts\lib.ps1 handles that.

Artifacts

Per run, in <repo>\.gnhf\runs\<runId>\ (gitignored by gnhf, so it never pollutes the branch):

File	Contents
`prompt.md`	The objective as given
`notes.md`	The agent's own iteration log — claims, not evidence
`end-state.json`	`status`, `stopCondition`, `agentError`, `iterations`, `successCount`, `failCount`, `endedAt`
`gnhf.log`	JSONL lifecycle log with timings and full `error.cause` chains
`iteration-<n>.jsonl`	Raw agent stream per iteration. Large; never copied to the vault
`base-commit`	Commit the run branched from
`stop-when`	Persisted stop condition

Behaviors that break unattended runs

Both are enforced by the wrapper's preflight; know them when diagnosing a failure.

Launching from a gnhf/* branch prompts interactively to overwrite/continue, and hard-fails when stdin is not a TTY: "Cannot show the overwrite prompt because stdin is not interactive."
An empty prompt with a non-TTY stdin makes gnhf read the prompt from stdin and block forever.

Also: gnhf requires a clean working tree, never force-pushes, never auto-pulls, and commits each successful iteration separately so a night can be reviewed or reverted one change at a time.

Docs

Upstream project: https://github.com/kunchenguid/gnhf (README.md, VISION.md).

The vendored package also ships its own README locally — no network needed: vendor\node_modules\gnhf\README.md.

This skill does not depend on a local clone of the gnhf source repo.

4.6 KiB Raw Blame History