gnhf是什么
gnhf（全称 good night, have fun）是开源的 AI Agent 自主编排器，核心理念是让开发者在睡前给 AI 设定一个目标，让它在你休息时持续迭代工作。每次只做一个小改动，成功便自动 git commit，失败则 git reset --hard 回滚，醒来时你的仓库分支上已满是干净的提交记录与完整日志。原生支持 Claude Code、Codex、GitHub Copilot CLI 等主流 AI 编程助手，具备跨迭代记忆共享、断点续跑、多任务 worktree 并行和实时 token 监控等能力，可通过 npm 一键安装，跨平台运行，采用 MIT 协议开源在 GitHub 上。
gnhf的主要功能
- 夜间自主迭代：只需睡前给 AI 设定一个开发目标，Agent 便在你休息时自动循环执行，每次仅做一个小改动，醒来即可查看完整成果。
- Git 纪律驱动：每次成功迭代自动生成独立的
git commit，失败迭代立即git reset --hard回滚，确保分支历史干净、可追溯。 - 智能容错与重试：Agent 报告的失败进入下一轮迭代，硬错误采用指数退避，永久错误（如 API 余额不足）立即中止并输出日志路径，连续 3 次失败后自动停止。
- 跨迭代记忆共享：Agent 通过
notes.md文件在多轮迭代间传递上下文与经验，实现持续积累而非从零开始。 - Worktree 并行：同一仓库可同时启动多个 gnhf 任务，每个拥有独立工作目录和分支，互不干扰，适合并行推进多项技术债务。
- 断点续跑：在已有的
gnhf/分支上重新运行命令，可自动恢复之前的任务进度，无需从头开始。 - 实时状态监控：交互式运行时在终端标题栏实时显示当前状态、累计 token 消耗和 commit 数量，方便随时掌握进展。
- 防休眠机制：运行期间自动阻止系统休眠，macOS 用
caffeinate，Linux 用systemd-inhibit，Windows 用 PowerShell 原生方案。 - 多 Agent 原生支持：开箱即用支持 Claude Code、Codex、GitHub Copilot CLI、Rovo Dev、OpenCode、Pi 六大主流 AI 编程助手，可通过配置自定义路径和参数。
- 灵活的运行时控制：支持
--max-iterations限制迭代次数、--max-tokens限制 token 总量、--stop-when设定自然语言停止条件。 - 零侵入式集成：所有操作仅在自动创建的
gnhf/分支上进行，主分支完全不受影响；worktree 模式甚至不会污染原仓库工作区。
如何使用gnhf
- 安装部署：通过
npm install -g gnhf全局安装，或从 GitHub 仓库克隆源码后执行npm install && npm run build && npm link本地构建。 - 基础启动：在目标仓库根目录运行
gnhf "你的开发目标"，例如gnhf "reduce complexity of the codebase without changing functionality"，工具会自动创建gnhf/分支并开始迭代。 - 限制迭代规模：使用
--max-iterations 10设定最大迭代次数，--max-tokens 5000000设定 token 消耗上限，避免资源失控。 - 设定自然语言停止条件：通过
--stop-when "所有测试通过"让 Agent 在满足特定条件时自动结束任务。 - 断点续跑：在已有的
gnhf/分支上重新运行gnhf命令，选择继续历史任务即可恢复之前的进度，无需从头开始 - 多任务并行：使用
gnhf --worktree "任务A" &和gnhf --worktree "任务B" &在同一仓库同时启动多个 Agent，每个拥有独立工作目录和分支。 - 自定义 Agent 配置：编辑
~/.gnhf/config.yml设置默认 Agent（如claude、codex、copilot等）、防休眠开关、自定义二进制路径及额外 CLI 参数。 - 查看运行日志：所有运行元数据保存在
.gnhf/runs/目录下，包含每次迭代的完整输入输出，便于审计和排查问题。 - 安全中止：运行期间按
Ctrl+C即可停止，或等待达到配置的上限后自动结束；连续 3 次失败后也会自动中止并提示日志路径。
gnhf的官网地址
- Github仓库：https://github.com/kunchenguid/gnhf
gnhf的关键信息和使用要求
- 项目全称：gnhf，即 good night, have fun，由开发者 kunchenguid 创建并开源
- 技术栈：TypeScript / Node.js，依赖 Git 作为版本控制底座
- 平台支持：macOS、Linux、Windows 三大主流操作系统
- 社区数据：上线约两周即收获 550+ GitHub Star，社区贡献 73 个活跃 PR
- 核心理念：睡前给 AI 设定一个开发目标，让它在你休息时持续迭代；每次只做一个小改动，成功则自动
git commit，失败则git reset --hard回滚 - 原生支持的 Agent：Claude Code、Codex、GitHub Copilot CLI、Rovo Dev、OpenCode、Pi 共六种主流 AI 编程助手
- 分支隔离机制：所有操作在自动创建的
gnhf/<slug>分支上执行，主分支完全不受影响，支持 worktree 独立工作目录 - 配置目录：运行时配置位于
~/.gnhf/config.yml，运行日志与元数据保存在仓库的.gnhf/runs/目录下
- 环境要求：系统需预先安装 Node.js 和 npm，且目标项目必须是一个 Git 仓库（gnhf 依赖 Git 进行 commit 和回滚操作）
- Agent 前置条件：需先在本地安装并配置至少一种支持的 AI 编程助手（如 Claude Code、Codex 等），并确保其 CLI 命令在系统 PATH 中可用
- API 资源准备：使用云端 Agent（如 Claude Code、Codex）需确保 API 账户有足够余额，否则会被识别为永久错误并立即中止
- 权限要求：运行目录需对当前用户可写，以便创建
gnhf/分支、.gnhf/日志目录及notes.md记忆文件 - 防休眠依赖：macOS 需系统支持
caffeinate命令，Linux 需systemd-inhibit，Windows 依赖 PowerShell，无对应工具时防休眠功能将静默失效 - 配置初始化：首次使用前建议编辑
~/.gnhf/config.yml指定默认 Agent 和偏好参数，避免每次命令行手动指定 - 运行监控：建议通过终端标题栏或
--max-tokens/--max-iterations参数设定资源上限，防止夜间 token 消耗失控 - 安全退出：运行期间可随时按
Ctrl+C中断，或依赖连续 3 次失败自动中止机制；异常退出后可通过日志路径.gnhf/runs/排查原因
gnhf的核心优势
- 夜间自动迭代，释放开发者时间：睡前布置任务，AI 在你休息时持续工作，醒来即可验收成果，将”碎片时间”和”睡眠时段”转化为有效开发产能。
- Git 纪律原生内建：每次成功改动自动
git commit，失败立即git reset --hard回滚，无需人工审查即可保证分支历史干净、可审计、随时可回退。 - 零侵入式隔离：所有操作限定在自动创建的
gnhf/分支，主分支完全不受影响；--worktree模式甚至为每个任务开辟独立工作目录，实现物理级隔离。 - 多 Agent 自由切换：原生支持 Claude Code、Codex、GitHub Copilot CLI、Rovo Dev、OpenCode、Pi 六大主流工具，不绑定单一厂商，可通过配置无缝切换或自定义扩展。
- 生产级容错与成本控制：连续 3 次失败自动中止，永久错误（如 API 余额不足）立即退出，配合
--max-tokens和--max-iterations硬上限，防止夜间资源失控。 - 断点续跑，进度不丢：在已有
gnhf/分支上重新运行即可恢复历史任务，无需从头开始，适合长周期复杂目标的持续攻坚。 - 跨迭代记忆积累：通过
notes.md在多轮迭代间传递上下文与失败教训，Agent 越跑越”聪明”，而非每次从零摸索。 - 同仓库多任务并行：
--worktree支持同一项目同时推进多项技术债务（如一个补测试、一个做重构），互不干扰，成倍提升吞吐。 - 自然语言级运行控制：
--stop-when允许用白话设定停止条件（如”所有测试通过”），无需编写复杂脚本即可精确控制任务边界。 - 跨平台开箱即用：支持 macOS、Linux、Windows，自动适配各平台防休眠机制，一条
npm install -g gnhf命令即可完成部署。
gnhf的应用场景
- 测试覆盖率补齐：针对遗留模块或新功能自动补充单元测试、集成测试，利用夜间时间将覆盖率从 60% 提升到 90% 而无需占用白天编码时间。
- 新功能渐进式实现：将大需求拆分为小目标（如”实现用户认证中间件”），让 Agent 夜间逐步迭代，每步成功即 commit，失败自动回滚，第二天验收合并。
- 多模块并行攻坚：同一项目同时启动多个 worktree 任务，例如一个 Agent 补测试、一个 Agent 做重构、一个 Agent 升级依赖，互不干扰地并行推进。
- 开源项目日常维护：自动处理标记为 “good first issue” 的简单重构、文档补全、依赖版本升级，维护者次日直接 review PR 即可。
- API 层重构与迁移：夜间自动完成接口参数调整、废弃方法替换、响应格式统一等低风险但耗时的机械改动，降低对白天业务开发的干扰。
- 代码风格与 Lint 治理：批量修复 ESLint/Prettier 警告、统一命名规范、移除未使用变量，保持代码库长期整洁而不占用核心开发精力。