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; hard agent errors back off exponentially while agent-reported failures continue immediately
- Live terminal title — interactive runs keep your terminal title updated with live status, token totals, and commit count, then restore the previous title on exit
- Agent-agnostic — works with Claude Code, Codex, Rovo Dev, or OpenCode out of the box
$ 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 nap# 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" &Run 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 │ │ maybe wait│ │
└────┬─────┘ └─────┬─────┘ │
│ │ │
│ ┌──────────┘ │
▼ ▼ │
┌────────────┐ 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
- Failure handling - all failed iterations are rolled back with
git reset --hard; agent-reported failures proceed to the next iteration immediately, while hard agent errors use exponential backoff - Runtime caps -
--max-iterationsstops before the next iteration begins,--max-tokenscan abort mid-iteration once reported usage reaches the cap, and--stop-whenends the loop after an iteration whose agent output reports the natural-language condition is met; uncommitted work is rolled back in either case, and in the interactive TUI the final state remains visible until you press Ctrl+C to exit - Iteration finalization - agents are expected to finish validation, stop any background processes they started, and only then emit the final JSON result for the iteration
- 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; if you provide a different prompt, gnhf asks whether to update the saved prompt and continue with the existing history, start a new branch, or quit
Pass --worktree to run each agent in an isolated git worktree. This lets you launch multiple agents on the same repo simultaneously — each gets its own working directory and branch without interfering with the others or your main checkout.
<repo>/ ← your repo (unchanged)
<repo>-gnhf-worktrees/
├── <run-slug-1>/ ← worktree for agent 1
└── <run-slug-2>/ ← worktree for agent 2
- Worktrees with commits are preserved after the run so you can review, merge, or cherry-pick the work. gnhf prints the path and cleanup command.
- Worktrees with no commits are automatically removed on exit.
--worktreemust be run from a non-gnhf branch (typicallymain).
| 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 |
If you run gnhf on an existing gnhf/ branch with a different prompt, gnhf asks whether to update prompt.md and continue the existing run history, start a new branch, or quit. When the prompt came from stdin, that confirmation is read from the controlling terminal, so it must be available.
| 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 |
--stop-when <cond> |
End the loop when the agent reports this natural-language condition is met | unlimited |
--prevent-sleep <mode> |
Prevent system sleep during the run (on/off or true/false) |
config file (on) |
--worktree |
Run in a separate git worktree (enables multiple agents concurrently) | false |
--version |
Show version |
Config lives at ~/.gnhf/config.yml:
# Agent to use by default (claude, codex, rovodev, or opencode)
agent: claude
# Custom paths to agent binaries (optional)
# agentPathOverride:
# claude: /path/to/custom-claude
# codex: /path/to/custom-codex
# Per-agent CLI arg overrides (optional)
# agentArgsOverride:
# codex:
# - -m
# - gpt-5.4
# - -c
# - model_reasoning_effort="high"
# - --full-auto
# 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.
agentArgsOverride.<name> lets you pass through extra CLI flags for any supported agent.
- Use it for agent-specific options like models, profiles, or reasoning settings without adding a dedicated
gnhfconfig field for each one. - For
codexandclaude,gnhfadds its usual non-interactive permission default only when you do not provide your own permission or execution-mode flag. If you set one explicitly,gnhftreats that as user-managed and does not add its default on top. - Flags that
gnhfmanages itself for a given agent, such as output-shaping or local-server startup flags, are rejected during config loading so you get a clear error instead of duplicate-argument ambiguity.
Use agentPathOverride to point any agent at a custom binary — useful for wrappers like Claude Code Switch or custom Codex builds that accept the same flags and arguments as the original:
agentPathOverride:
claude: ~/bin/claude-code-switch
codex: /usr/local/bin/my-codex-wrapperPaths may be absolute, bare executable names already on your PATH, ~-prefixed, or relative to the config directory (~/.gnhf/). The override replaces only the binary name; all standard arguments are preserved, so the replacement must be CLI-compatible with the original agent. On Windows, .cmd and .bat wrappers are supported, including bare names resolved from PATH. For rovodev, the override must point to an acli-compatible binary since gnhf invokes it as <bin> rovodev serve ....
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.
Every run writes a JSONL debug log to .gnhf/runs/<runId>/gnhf.log alongside notes.md. Lifecycle events for the orchestrator, agent, and HTTP requests are captured with elapsed timings and (for failures) the full error.cause chain — which is what you need to tell a bare TypeError: fetch failed apart from an undici UND_ERR_HEADERS_TIMEOUT. The agent's own streaming output still goes to the per-iteration iteration-<n>.jsonl file next to it.
Including a snippet of gnhf.log is the single most useful thing you can attach when filing an issue.
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. After Claude emits a successful structured result, gnhf treats that result as final and shuts down any lingering Claude process tree after a short grace period. |
| 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. |
If you want to contribute changes back to this repo, see CONTRIBUTING.md. Human-authored PRs targeting main must be opened via git push no-mistakes so the required Require no-mistakes check passes.
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