gnhf runs coding agents in a loop and lets git hold the receipts

A loop, one small commit at a time

The pitch is a joke that turns out to be a specification. The repository description reads: before I go to bed, I tell my agents, good night, have fun. The README frames gnhf as a ralph-style and autoresearch-style orchestrator that keeps agents running while you sleep, where each iteration makes one small, committed, documented change towards an objective.

That last clause is the whole contract. One small change, per iteration, committed, documented. The unit of progress is a commit rather than a session, which is what makes the run reviewable in the morning. The README's summary of what you get is: you wake up to a branch full of clean work and a log of everything that happened.

The quick start is a single command with an objective as a quoted argument:

$ gnhf "reduce complexity of the codebase without changing functionality"

Everything else is optional tuning. A second example bounds the run twice, with an iteration cap and a token cap, and the trailing comment shifts from a good sleep to a good nap. That is a useful signal about the intended scale. A loop bounded by nothing runs until you stop it or until a configured runtime cap, which is fine for an overnight experiment and a bad idea in a repository you care about.

The startup requirement is strict and worth repeating: run gnhf from inside a Git repository with a clean working tree. If you are starting from a plain directory, run git init first. That precondition is not ceremony, since it is what makes the rollback rules safe.

Failure handling as the actual design

The How It Works section is a flow diagram followed by five bullets, and the bullets are where the engineering is.

On success, each iteration becomes a separate unsigned git commit. Unsigned is a deliberate choice, and the reason is stated: so you can cherry-pick or revert individual changes without GPG or SSH signing prompts blocking the run. An unattended loop that stops at midnight waiting for a passphrase has failed, and the author has clearly thought about that.

On failure, the default is a hard reset back to the last good commit. The exception is commit failure: if git commit itself fails, gnhf does not reset. It preserves the uncommitted work and asks the next agent iteration to repair it. That is a small exception with a large consequence. A reset would destroy exactly the work the agent just did, so the tool keeps it and treats the commit as a problem to solve on the next pass. An agent that reported failure otherwise proceeds immediately to the next iteration.

The loop aborts on three consecutive failures or on a permission error, according to the diagram. Both conditions are sensible: repeated failure means the objective is not reachable by this agent and continuing burns tokens, and a permission error means something outside the loop's control is blocking it.

Worktrees for parallel attempts

The third quick start block runs several instances against the same repository, which requires isolating them:

# Run multiple agents on the same repo simultaneously using worktrees
$ gnhf --worktree "implement feature X" &
$ gnhf --worktree "add tests for module Y" &
$ gnhf --worktree "refactor the API layer" &

Each run gets its own git worktree, so three objectives can proceed at once without two agents editing the same file. This is the feature that turns gnhf from a curiosity into something a team might run, since the interesting version of overnight work is three agents attempting three independent improvements rather than one agent attempting one improvement.

The fourth example goes the other way. With --current-branch, the loop commits directly on the branch you are already on, and with --push it pushes after each successful iteration. That combination is the one to think twice about, because a hard reset on a shared branch discards anything else you committed in the meantime.

The remaining surface is about what you can see while it runs. Interactive runs keep the terminal title updated with live status, token totals and commit count, then clear or restore the title on exit depending on terminal support. Token totals prefixed with a tilde are estimates, which is an honest admission that the number is derived rather than measured from a provider bill.

Two runtime dependencies, node 20, tsdown

The package.json is a good place to calibrate expectations about how much machinery is involved. A tool that orchestrates coding agents across CLIs and any ACP target has exactly two runtime dependencies: commander at ^14.0.3 for argument parsing and js-yaml at ^4.1.1 for configuration. Everything else is a dev dependency, including acpx at ^0.6.1 and an ACP mock, which are how the agent-agnostic claim is tested.

The build is tsdown, the same bundler the AXI sibling repository uses, and the binary is a single entry point registered as dist/cli.mjs. The engines field requires node 20 or newer. The published files list is dist, skills, LICENSE and README.md, so the agent skill ships inside the npm package rather than being fetched at run time.

The test scripts are worth noting because they reveal what the author thinks is hard. The default test script builds first and then runs vitest, so tests run against the built artifact rather than the source. There is a separate e2e script that runs the e2e directory, and a coverage script that excludes e2e from coverage. An e2e directory at the root means the loop is exercised end to end, presumably against a mocked agent rather than a real one, given acp-mock is a dev dependency.

The project also carries the standard release-please files, a CHANGELOG.md, an AGENTS.md, a CLAUDE.md, a VISION.md, and an .airlock directory whose purpose the README does not explain.

An agent skill describing two ways to run it

The npm package includes an agent-facing skill at skills/gnhf/SKILL.md, and the README explains why in one paragraph: agents that support local skills can copy or reference this file to learn how to run gnhf in Hands-Off mode for bounded overnight work, or Companion mode when the outer agent should steer and review a long-running run.

Those two modes are the interesting design decision. Hands-Off is the loop described above. Companion is the same loop with another agent in charge, which is a recursive arrangement that is either very clever or a good way to spend a lot of tokens, and the fact that the author documents both suggests the second mode is the one that gets used when the objective is vague enough that you want supervision.

This is a coherent pattern across both of this author's repositories: AXI argues for ambient context, that agents should find tools without being told, and gnhf ships a skill inside the package. The two projects share a Discord invite and a badge wall style, and both treat the agent's own documentation as a shipped artifact rather than a README you have to describe to it.

Three releases in six days is the last thing the repository data says. gnhf-v0.1.47 published on 2026-08-30, gnhf-v0.1.48 on 2026-09-02, and gnhf-v0.1.49 on 2026-09-04, and the package version in package.json matches the last of those at 0.1.49. The 0.1 prefix has not moved, so the command line interface should be expected to change. Seventeen open issues against 4,073 stars suggests either that the tool works or that the discussion happens in Discord rather than on the tracker.

Editorial conclusion

gnhf's real contribution is not autonomy, it is bookkeeping. The idea that every iteration should be a separate unsigned commit, with failure meaning a hard reset back to the last good state, converts an unattended agent run from a thing you inspect into a thing you replay. That design also dictates the sharp edges: a hard reset is only safe because the tool insists on a clean working tree at startup, an unsigned commit is only safe because your signing setup cannot prompt, and the loop stops only when you stop it, when a runtime cap is reached, or after three consecutive failures. Give it a repository you would be willing to reset, read the exit summary before you touch the branch, and cherry-pick rather than merge.

Frequently asked questions

Official sources

1. Issues
2. kunchenguid/gnhf on GitHub
3. License: MIT
4. README
5. Releases