kunchenguid/gnhf: Autonomous Agent Orchestrator for Overnight Coding

kunchenguid/gnhf: Autonomous Agent Orchestrator for Overnight Coding

Developers increasingly rely on AI coding agents to handle repetitive tasks, but there's a persistent gap: what happens when you need to step away? Most agent tools require active supervision—approving changes, resolving conflicts, monitoring progress. The promise of "set it and forget it" remains elusive for multi-hour or overnight workflows. kunchenguid/gnhf addresses this directly. It's an autonomous orchestrator that keeps your agents running while you sleep, committing incremental progress and maintaining a clean audit trail. With 3,200 GitHub stars and 229 forks, this MIT-licensed TypeScript project has gained meaningful traction among developers who need reliable, long-running agent execution without babysitting their terminal.

What is kunchenguid/gnhf?

kunchenguid/gnhf ("good night, have fun") is a command-line orchestrator for AI coding agents, maintained by @kunchenguid. The project falls into the emerging category of agent infrastructure or agent orchestration tools—software that manages the lifecycle of autonomous coding agents rather than being an agent itself.

The tool's design philosophy draws from ralph and autoresearch-style systems: each iteration makes one small, committed, documented change toward a stated objective. You wake up to a branch containing clean, discrete commits with a full log of what occurred.

Technically, gnhf is built in TypeScript, distributed via npm, and supports macOS, Linux, and Windows. It integrates with six native agent CLIs (Claude Code, Codex, GitHub Copilot CLI, Pi, Rovo Dev, OpenCode) plus any ACP-compatible target through its bundled acpx runtime. The project reached 3,200 stars and 229 forks as of its last commit on July 10, 2026, indicating sustained community interest in hands-off agent workflows.

What distinguishes gnhf from simply running an agent in a loop is its failure-handling rigor: successful iterations become atomic git commits, failures trigger rollback or repair protocols, and the system aborts on permanent errors (like insufficient API credits) rather than burning tokens uselessly. This makes it genuinely suitable for unattended operation—hence the project's tagline: "Never wake up empty-handed."

Key Features

Dead-simple invocation — A single command starts the autonomous loop. The tool validates a clean git state, creates or reuses a branch, writes your prompt to prompt.md, and begins iterating. No configuration files to edit for basic usage.

Atomic iteration commits — Each successful iteration produces a separate, unsigned git commit. This design deliberately avoids GPG or SSH signing prompts that would block unattended operation. If git commit itself fails, gnhf preserves uncommitted work and directs the next agent iteration to repair it.

Structured failure handling — Failed iterations roll back via git reset --hard (except commit failures, which enter repair mode). Agent-reported failures proceed immediately to the next iteration; retryable hard errors use exponential backoff; permanent errors (e.g., Claude low credit balance) abort instantly and print the log path. Three consecutive failures or any permanent error triggers full abort.

Runtime safety caps — --max-iterations, --max-tokens, and --stop-when provide multiple guardrails. The stop condition persists across resumed runs. Token totals display with ~ prefix when estimated.

Live terminal feedback — Interactive runs update your terminal title with real-time status, token totals, and commit count. The TUI restores or clears the title on exit depending on terminal capability.

Comprehensive exit summary — Every run concludes with elapsed time, branch name, iteration count, token totals, branch diff stats, and exact paths to notes/logs and review commands.

Agent-agnostic architecture — Native support for six major coding agents plus any ACP target. Configuration at ~/.gnhf/config.yml lets you override binary paths, pass custom arguments, and set commit message conventions including Conventional Commits.

Resume and worktree support — Resume interrupted runs from gnhf/ branches. Launch multiple simultaneous agents on the same repository via --worktree, each isolated in their own git worktree with preserved branches for later review.

Use Cases

Overnight refactoring campaigns — Run gnhf "reduce complexity of the codebase without changing functionality" before leaving work. Return to a branch with dozens of small, reviewable commits, each documented in notes.md.

Parallel feature exploration — Launch multiple worktree instances to explore competing implementations: gnhf --worktree "implement feature X" & alongside gnhf --worktree "alternative approach for feature X" &. Compare branches the next morning without polluting your main checkout.

Continuous integration augmentation — Combine --current-branch --push with a watched deployment branch. Each successful iteration pushes automatically, triggering CI/CD pipelines for immediate feedback on agent-generated changes.

Long-running test generation — Direct gnhf to add comprehensive test coverage for a specific module. The cap system (--max-tokens 5000000) prevents runaway token consumption while you attend to other work.

Hands-off research and documentation — Use --stop-when with a natural-language condition like "all public APIs have JSDoc comments" for bounded documentation sprints that self-terminate when objectives are met.

Installation & Setup

Prerequisites: Node.js and a clean git repository. If starting from a plain directory, run git init first.

Via npm (recommended):

npm install -g gnhf

This installs the gnhf command globally along with the bundled agent skill at skills/gnhf/SKILL.md.

From source:

git clone https://github.com/kunchenguid/gnhf.git
cd gnhf
corepack enable
pnpm install
pnpm run build
pnpm link --global

The source build requires corepack for package manager enforcement, then standard pnpm workflow.

Post-installation configuration:

On first run, gnhf creates ~/.gnhf/config.yml with sensible defaults:

# Default configuration created automatically
agent: claude
maxConsecutiveFailures: 3
preventSleep: true

Edit this file to override agent binary paths, add custom arguments, configure ACP targets, or set commit message conventions. CLI flags always override config file values.

Agent prerequisites: Install and authenticate at least one supported agent CLI before running gnhf. For Claude Code: claude CLI with active Anthropic login. For Codex: OpenAI's codex CLI with authentication. See the Agents section in the project README for per-agent requirements.

Real Code Examples

Basic overnight run:

$ gnhf "reduce complexity of the codebase without changing functionality"
# have a good sleep

This single command validates git cleanliness, creates a gnhf/ branch, and loops until interrupted, capped, or failed out. The comment # have a good sleep reflects the tool's intended use case—genuine unattended operation.

Bounded run with explicit caps:

$ gnhf "reduce complexity of the codebase without changing functionality" \
    --max-iterations 10 \
    --max-tokens 5000000
# have a good nap

Here we limit both iteration count and token expenditure. This pattern suits shorter unattended periods or cost-sensitive environments. The --max-tokens cap can abort mid-iteration once reported usage exceeds the threshold.

Parallel worktree execution:

# 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 & backgrounds a separate process with its own git worktree under <repo>-gnhf-worktrees/<run-slug>/. This enables true parallelism without working directory conflicts. Worktrees with commits persist after exit for manual review, merge, or cherry-pick.

Live branch with auto-push:

# Commit directly on the current branch and push after each successful iteration
$ gnhf --current-branch --push "keep improving this app"

The --current-branch flag skips gnhf/ branch creation, operating directly on your checked-out branch. --push sends each commit to origin immediately. This combination suits projects where you want deployed or watched branches to update continuously. Note: gnhf never force-pushes or auto-pulls in this mode.

Piped prompt from file:

cat prd.md | gnhf

For lengthy specifications, pipe PRDs or design documents directly rather than wrestling with shell quoting. When using stdin for prompts, confirmation prompts (e.g., for resume branch conflicts) read from the controlling terminal, so TTY availability is required.

Advanced Usage & Best Practices

Resume hygiene: When resuming a run on an existing gnhf/ branch with a different prompt, gnhf asks whether to update prompt.md and continue history, start a new branch, or quit. For automated environments, consider this interaction carefully—stdin prompts may hang unattended scripts.

Sleep prevention: Enabled by default via preventSleep: true. Uses caffeinate on macOS, systemd-inhibit on Linux, and PowerShell with SetThreadExecutionState on Windows. Disable with --prevent-sleep off for environments where system sleep is desirable or power management is externally controlled.

Commit conventions: The default format is gnhf <iteration>: <summary>. Switch to Conventional Commits by setting commitMessage.preset: conventional in config—useful for semantic-release workflows. The resolved convention persists per-run, so resumed runs maintain consistency even if you later change config.

Custom ACP agents: Beyond registered targets, pass raw commands: gnhf --agent 'acp:./bin/dev-acp --profile ci' "fix the tests". Note that agentPathOverride and agentArgsOverride do not apply to ACP targets in the current version; use acpRegistryOverrides or inline specs instead.

Debugging failures: Every run writes gnhf.log as JSONL under .gnhf/runs/<runId>/. This captures lifecycle events, HTTP timings, and full error.cause chains—including the distinction between bare TypeError: fetch failed and UND_ERR_HEADERS_TIMEOUT. The project maintainer explicitly identifies this as "the single most useful thing you can attach when filing an issue."

Comparison with Alternatives

gnhf occupies a specific niche: you already have preferred agent tools installed and authenticated, but need reliable infrastructure for overnight or parallel execution. It adds no proprietary model or IDE—just disciplined orchestration. The trade-off is configuration responsibility: you manage agent credentials, model selection, and cost exposure directly with each provider.

FAQ

Is kunchenguid/gnhf free? Yes, MIT licensed. You pay only for agent API usage through your chosen providers.

Which agents work out of the box? Claude Code, Codex, GitHub Copilot CLI, Pi, Rovo Dev, OpenCode, plus any ACP-compatible target.

Can I run multiple agents simultaneously? Yes, via --worktree. Each gets an isolated git worktree and branch.

What happens if my API credits run out? Permanent errors like Claude low credit balance abort immediately with the log path printed.

Does it work on Windows? Yes, with full support including sleep prevention via PowerShell.

How do I disable telemetry? Set environment variable GNHF_TELEMETRY=0.

Can I resume an interrupted run? Yes—run gnhf from an existing gnhf/ branch to continue with preserved history.

Conclusion

kunchenguid/gnhf solves a concrete infrastructure problem for developers using AI coding agents: reliable, unattended, long-running execution with proper git hygiene and failure recovery. It's not an agent itself, but the disciplined orchestration layer that makes existing agents production-ready for overnight and parallel workloads.

The tool suits teams and individuals who: already use Claude Code, Codex, or similar agents; need to scale agent work across time (overnight) or space (parallel worktrees); value atomic, reviewable commits over monolithic changes; and want open-source, self-hosted infrastructure without vendor lock-in.

With 3,200 stars, active maintenance through mid-2026, and a clear technical scope, gnhf represents a mature approach to agent orchestration. Install via npm install -g gnhf or build from source, configure your preferred agent, and run your first overnight job with gnhf "your objective here".

Explore the repository, read the full documentation, and star the project at https://github.com/kunchenguid/gnhf.