Before I go to bed, I tell my agents:
Never wake up empty-handed.
gnhf is a ralph, autoresearch-style orchestrator that keeps your agents running while you sleep — each iteration makes one small, committed, documented change towards an objective. You wake up to a branch full of clean work and a log of everything that happened.
- Dead simple — one command starts an autonomous loop that runs until you Ctrl+C or a configured runtime cap is reached
- Long running — each iteration is committed on success, rolled back on failure, with sensible retries and exponential backoff
- Agent-agnostic — works with Claude Code, Codex, Rovo Dev, or OpenCode out of the box
- Terminal-safe rendering — the live UI keeps wide Unicode text such as emoji and CJK glyphs aligned instead of clipping or shifting the frame
$ gnhf "reduce complexity of the codebase without changing functionality"
# have a good sleep$ gnhf "reduce complexity of the codebase without changing functionality" \
--max-iterations 10 \
--max-tokens 5000000
# have a good napRun gnhf from inside a Git repository with a clean working tree. If you are starting from a plain directory, run git init first.
gnhf supports macOS, Linux, and Windows.
npm
npm install -g gnhfFrom source
git clone https://github.com/kunchenguid/gnhf.git
cd gnhf
npm install
npm run build
npm link ┌─────────────┐
│ gnhf start │
└──────┬──────┘
▼
┌──────────────────────┐
│ validate clean git │
│ create gnhf/ branch │
│ write prompt.md │
└──────────┬───────────┘
▼
┌────────────────────────────┐
│ build iteration prompt │◄──────────────┐
│ (inject notes.md context) │ │
└────────────┬───────────────┘ │
▼ │
┌────────────────────────────┐ │
│ invoke your agent │ │
│ (non-interactive mode) │ │
└────────────┬───────────────┘ │
▼ │
┌─────────────┐ │
│ success? │ │
└──┬──────┬───┘ │
yes │ │ no │
▼ ▼ │
┌──────────┐ ┌───────────┐ │
│ commit │ │ git reset │ │
│ append │ │ --hard │ │
│ notes.md │ │ backoff │ │
└────┬─────┘ └─────┬─────┘ │
│ │ │
│ ┌──────────┘ │
▼ ▼ │
┌────────────┐ yes ┌──────────┐ │
│ 3 consec. ├─────────►│ abort │ │
│ failures? │ └──────────┘ │
└─────┬──────┘ │
no │ │
└──────────────────────────────────────┘
- Incremental commits — each successful iteration is a separate git commit, so you can cherry-pick or revert individual changes
- Runtime caps —
--max-iterationsstops before the next iteration begins, while--max-tokenscan abort mid-iteration once reported usage reaches the cap; uncommitted work is rolled back in either case - Shared memory — the agent reads
notes.md(built up from prior iterations) to communicate across iterations - Local run metadata — gnhf stores prompt, notes, and resume metadata under
.gnhf/runs/and ignores it locally, so your branch only contains intentional work - Resume support — run
gnhfwhile on an existinggnhf/branch to pick up where a previous run left off
| Command | Description |
|---|---|
gnhf "<prompt>" |
Start a new run with the given objective |
gnhf |
Resume a run (when on an existing gnhf/ branch) |
echo "<prompt>" | gnhf |
Pipe prompt via stdin |
cat prd.md | gnhf |
Pipe a large spec or PRD via stdin |
| Flag | Description | Default |
|---|---|---|
--agent <agent> |
Agent to use (claude, codex, rovodev, or opencode) |
config file (claude) |
--max-iterations <n> |
Abort after n total iterations |
unlimited |
--max-tokens <n> |
Abort after n total input+output tokens |
unlimited |
--prevent-sleep <mode> |
Prevent system sleep during the run (on/off or true/false) |
config file (on) |
--version |
Show version |
Config lives at ~/.gnhf/config.yml:
# Agent to use by default (claude, codex, rovodev, or opencode)
agent: claude
# Abort after this many consecutive failures
maxConsecutiveFailures: 3
# Prevent the machine from sleeping during a run
preventSleep: trueIf the file does not exist yet, gnhf creates it on first run using the resolved defaults.
CLI flags override config file values. --prevent-sleep accepts on/off as well as true/false; the config file always uses a boolean.
The iteration and token caps are runtime-only flags and are not persisted in config.yml.
When sleep prevention is enabled, gnhf uses the native mechanism for your OS: caffeinate on macOS, systemd-inhibit on Linux, and a small PowerShell helper backed by SetThreadExecutionState on Windows.
Set GNHF_DEBUG_LOG_PATH to capture lifecycle events as JSONL while debugging a run:
GNHF_DEBUG_LOG_PATH=/tmp/gnhf-debug.jsonl gnhf "ship it"gnhf supports four agents:
| Agent | Flag | Requirements | Notes |
|---|---|---|---|
| Claude Code | --agent claude |
Install Anthropic's claude CLI and sign in first. |
gnhf invokes claude directly in non-interactive mode. |
| Codex | --agent codex |
Install OpenAI's codex CLI and sign in first. |
gnhf invokes codex exec directly in non-interactive mode. |
| Rovo Dev | --agent rovodev |
Install Atlassian's acli and authenticate it with Rovo Dev first. |
gnhf starts a local acli rovodev serve --disable-session-token <port> process automatically in the repo workspace. |
| OpenCode | --agent opencode |
Install opencode and configure at least one usable model provider first. |
gnhf starts a local opencode serve --hostname 127.0.0.1 --port <port> --print-logs process automatically, creates a per-run session, and applies a blanket allow rule so tool calls do not block on prompts. |
npm run build # Build with tsdown
npm run dev # Watch mode
npm test # Build, then run unit tests (vitest)
npm run test:e2e # Build, then run end-to-end tests against the mock opencode executable
npm run lint # ESLint
npm run format # Prettier