gnhf 开源：给 AI 助手一句目标去睡觉，醒来收获干净的分支和提交

最近，我发现了一个特别有意思的开源项目，名字叫gnhf—— 全称是**"good night, have fun"（晚安，玩得开心）**。

这个名字起得很有画面感，它确实能做到一件很酷的事情：让 AI 编码助手在你睡觉的时候，按照 Git 纪律持续改进代码。
只需要你晚上睡觉前，给 gnhf 一个目标，比如"给这个模块补充测试"、"清理重复逻辑"或者"降低代码复杂度"，然后安心去睡觉。
第二天早上醒来，你会看到一个分支，里面全是干净的工作成果，还有详细的执行日志。这种感觉，就像有一位勤奋的开发搭档，在你休息的时候默默工作。

项目简介

gnhf是一个 ralph、autoresearch 风格的编排器（orchestrator），它能让你的 coding agent 在你睡觉时持续运行。

每一次迭代，它都会向目标推进一小步，并且遵循严格的 Git 纪律：
•成功就提交：每一次成功的改动都会变成一个独立的 Git 提交
•失败就回滚：如果某次迭代失败了，会自动用 git reset --hard 回滚
•记录全过程：所有的工作过程都会被记录在 notes.md 中
•核心代码留审核：核心业务逻辑还是需要人工审核，gnhf 更适合处理机械性、重复性的工作
它完全用 TypeScript 编写，支持 macOS、Linux 和 Windows 三大操作系统。

三大核心优势

1️⃣ 超级简单，一条命令就够了
gnhf 的设计理念就是"简单到极致"。你不需要复杂的配置，只需要一条命令就能启动一个自动循环，它会一直运行，直到你按 Ctrl+C 或者达到配置的运行上限。

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

2️⃣ 长时间运行，容错能力强
gnhf 特别设计用于长时间运行：
•成功提交：每次成功的迭代都是一个独立的 git commit，你可以单独 cherry-pick 或回滚
•失败回滚：失败的迭代会用 git reset --hard 回滚
•智能重试：有合理的重试机制，硬错误会用指数退避，agent 报告的失败会立即继续
•运行上限：可以设置 --max-iterations（最大迭代次数）或 --max-tokens（最大 token 数）来控制
3️⃣ 支持多种主流工具
gnhf 是 agent-agnostic 的，这意味着它不绑定任何特定的 AI 编码助手，开箱即用支持：
• Claude Code
• Codex
• Rovo Dev
• OpenCode
• GitHub Copilot CLI（最近刚加入）
• Pi coding agent（最新支持）
你可以用你最习惯的那个，gnhf 都能很好地配合。

如何工作？

让我们看看 gnhf 的工作流程：

 ┌─────────────┐
 │ 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 │ │
 └──────────────────────────────────────┘

这个流程很清晰：
1.启动验证：首先验证 Git 工作树是干净的，创建专门的 gnhf/ 分支，写入目标提示
2.迭代循环：每次迭代都会构建提示（注入 notes.md 的上下文），调用 agent
3.成功/失败处理：成功就提交并追加 notes.md，失败就重置回滚
4.失败保护：连续 3 次失败就中止运行
还有几个很实用的特性：
•共享记忆：agent 读取 notes.md（从之前的迭代积累）来跨迭代沟通
•本地元数据：gnhf 把提示、笔记和恢复元数据存储在 .gnhf/runs/ 下，本地忽略，所以你的分支只包含有意的工作
•恢复支持：在已存在的 gnhf/ 分支上运行 gnhf 可以从上次中断的地方继续

快速上手

最简单的安装方式是用 npm 全局安装：

npm install -g gnhf

如果想从源码安装：

git clone https://github.com/kunchenguid/gnhf.git
cd gnhf
npm install
npm run build
npm link

然后确保你在一个干净的 Git 仓库中：

cd your-project
git status  # 确保是 clean 的

如果是一个新目录，先初始化 Git：

git init

设置你的目标，启动 gnhf：

gnhf "reduce complexity of the codebase without changing functionality"

或者设置运行上限（适合午睡）：

gnhf "reduce complexity of the codebase without changing functionality" \
 --max-iterations 10 \
 --max-tokens 5000000

然后就可以去休息了！
进阶玩法：Worktree 模式
这个功能特别厉害——你可以用 --worktree 参数让多个 agent 同时在同一个仓库上运行，互不干扰：

# 同时运行多个 agent
$ gnhf --worktree "implement feature X" &
$ gnhf --worktree "add tests for module Y" &
$ gnhf --worktree "refactor the API layer" &

工作原理是利用 git worktree，每个 agent 都有自己独立的工作目录和分支，不会互相干扰，也不会影响你的主 checkout：

<repo>/ ← 你的仓库（保持不变）
<repo>-gnhf-worktrees/
 ├── <run-slug-1>/ ← agent 1 的 worktree
 └── <run-slug-2>/ ← agent 2 的 worktree

有几点注意：
• 有提交的 worktree 会保留下来，供你查看、合并或 cherry-pick
• 没有提交的 worktree 会在退出时自动清理
• --worktree 必须从非 gnhf 分支运行（通常是 main）
CLI 完整参考，基本命令

# 默认使用的 agent（claude、codex、rovodev、opencode、copilot、pi）
agent: claude

# 自定义 agent 二进制文件路径（可选）
# agentPathOverride:
# claude: /path/to/custom-claude
# codex: /path/to/custom-codex

# 每个 agent 的 CLI 参数覆盖（可选）
# agentArgsOverride:
# codex:
# - -m
# - gpt-5.4
# - -c
# - model_reasoning_effort="high"
# - --full-auto

# 连续这么多次失败后中止
maxConsecutiveFailures: 3

# 运行期间防止机器睡眠
preventSleep: true

如果文件不存在，gnhf 会在首次运行时用解析后的默认值创建它。
CLI 参数会覆盖配置文件值。--prevent-sleep接受on/off以及true/false；配置文件总是使用布尔值。迭代和 token 上限是仅限运行时的参数，不会持久化在 config.yml 中。

写在最后

gnhf是一个特别有创意的工具，它把 AI 编码助手的能力和 Git 的纪律完美结合起来。
它的设计理念很简单，但解决的问题很实在：让机械性的编码工作在你休息的时候自动完成，第二天醒来收获干净的成果。
这个项目还在快速迭代中，最近刚加入了对 GitHub Copilot CLI 和 Pi coding agent 的支持，未来应该会有更多惊喜。
如果你经常被重复性的编码工作困扰，或者想在晚上让 AI 帮你做些基础工作，不妨试试 gnhf。
GitHub：https://github.com/kunchenguid/gnhf