# gnhf

> An open-source CLI orchestrator that keeps your AI coding agents running autonomously overnight, committing incremental changes while you sleep.

gnhf ("good night, have fun") is an open-source CLI tool built by Kun Chen that lets you hand off a coding objective to an AI agent before bed and wake up to a branch full of clean, committed work. It runs on macOS, Linux, and Windows, is installable via npm, and is licensed under MIT. The project has accumulated over 2,600 GitHub stars since its creation in early 2026.

## What It Is

gnhf is an autonomous agent orchestrator in the style of ralph and autoresearch-style loops. You give it a natural-language objective, and it drives a supported AI coding agent — Claude Code, Codex, GitHub Copilot CLI, Rovo Dev, OpenCode, Pi, or any ACP target — in a non-interactive loop. Each iteration makes one small, committed, documented change toward the goal. If an iteration fails, gnhf rolls it back and retries; if it succeeds, the change is committed to a dedicated `gnhf/` branch. The result is a reviewable branch diff and a structured log of everything that happened.

## How the Iteration Loop Works

The core loop is straightforward: gnhf validates a clean git state, creates or reuses a branch, writes a `prompt.md`, then repeatedly builds an iteration prompt (injecting accumulated `notes.md` context), invokes the agent in non-interactive mode, and either commits the result or resets on failure.

Key behaviors:
- **Incremental commits** — each successful iteration is a separate unsigned git commit, cherry-pickable or revertable individually
- **Failure handling** — agent-reported failures proceed immediately to the next iteration; retryable hard errors use exponential backoff; permanent errors (e.g., low credit balance) abort and print the log path
- **Runtime caps** — `--max-iterations`, `--max-tokens`, and `--stop-when` give fine-grained control over when the loop ends
- **Shared memory** — `notes.md` accumulates context across iterations so the agent can build on prior work
- **Resume support** — re-running on an existing `gnhf/` branch picks up where the previous run left off

## Worktree and Branch Modes

gnhf supports three operating modes. The default creates a `gnhf/<slug>` branch. `--current-branch` runs on the branch you are already on, optionally with `--push` to push after each successful iteration. `--worktree` runs each agent in an isolated git worktree, enabling multiple agents to work on the same repo simultaneously without interfering with each other or the main checkout. Worktrees with commits are preserved after the run for review, merge, or cherry-pick.

## Agent Support and ACP Integration

gnhf is agent-agnostic by design. It supports six native agents out of the box — Claude Code, Codex, GitHub Copilot CLI, Pi, Rovo Dev, and OpenCode — plus any ACP target via the bundled `acpx` runtime. ACP support enables integration with agents like Gemini or custom local ACP server commands. Configuration lives at `~/.gnhf/config.yml` and supports default agent selection, custom binary paths, per-agent CLI arg overrides, commit message conventions (including conventional commits for semantic-release workflows), and sleep prevention settings.

## Update: v0.1.42

The latest release is gnhf v0.1.42, published in May 2026. The project shows active development with CI and release automation via GitHub Actions, a vitest-based test suite including end-to-end tests against a mock OpenCode executable, and regular releases tracked via release-please. The repository was created in March 2026 and has seen consistent push activity through June 2026, signaling an actively maintained early-stage project.

## Features
- Autonomous overnight agent loop
- Incremental git commits per iteration
- Rollback on failure with exponential backoff for retryable errors
- Resume support for existing gnhf/ branches
- Worktree mode for concurrent multi-agent runs
- Live terminal title with status, token totals, and commit count
- Exit summary with elapsed time, branch diff stats, and review commands
- Runtime caps via --max-iterations, --max-tokens, and --stop-when
- Shared memory via notes.md across iterations
- Support for Claude Code, Codex, Copilot CLI, Rovo Dev, OpenCode, Pi, and ACP targets
- Conventional commit message preset for semantic-release workflows
- Custom agent binary path overrides
- Per-agent CLI arg overrides
- Anonymous telemetry with opt-out via GNHF_TELEMETRY=0
- JSONL debug log per run
- Sleep prevention during runs (caffeinate/systemd-inhibit/PowerShell)
- Graceful interrupt handling with two-stage Ctrl+C
- Pipe prompt via stdin or from a file

## Integrations
Claude Code, OpenAI Codex, GitHub Copilot CLI, Rovo Dev (Atlassian acli), OpenCode, Pi CLI, ACP (Agent Communication Protocol) via acpx, Gemini (via ACP), Git, npm

## Platforms
WINDOWS, MACOS, LINUX, WEB, API, CLI

## Pricing
Open Source

## Version
0.1.42

## Links
- Website: https://github.com/kunchenguid/gnhf
- Documentation: https://github.com/kunchenguid/gnhf#readme
- Repository: https://github.com/kunchenguid/gnhf
- EveryDev.ai: https://www.everydev.ai/tools/gnhf