gnhf 0.1.25 → 0.1.27
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +44 -16
- package/dist/cli.mjs +799 -69
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -44,10 +44,10 @@ Never wake up empty-handed.
|
|
|
44
44
|
gnhf is a [ralph](https://ghuntley.com/ralph/), [autoresearch](https://github.com/karpathy/autoresearch)-style orchestrator that keeps your agents running while you sleep — each iteration makes one small, committed, documented change towards an objective.
|
|
45
45
|
You wake up to a branch full of clean work and a log of everything that happened.
|
|
46
46
|
|
|
47
|
-
- **Dead simple** — one command starts an autonomous loop that runs until you
|
|
47
|
+
- **Dead simple** — one command starts an autonomous loop that runs until you request stop or a configured runtime cap is reached
|
|
48
48
|
- **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
|
|
49
49
|
- **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
|
|
50
|
-
- **Agent-agnostic
|
|
50
|
+
- **Agent-agnostic**: works with Claude Code, Codex, Rovo Dev, OpenCode, GitHub Copilot CLI, or Pi out of the box
|
|
51
51
|
|
|
52
52
|
## Quick Start
|
|
53
53
|
|
|
@@ -137,7 +137,9 @@ npm link
|
|
|
137
137
|
|
|
138
138
|
- **Incremental commits** — each successful iteration is a separate git commit, so you can cherry-pick or revert individual changes
|
|
139
139
|
- **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
|
|
140
|
-
- **Runtime caps** - `--max-iterations` stops before the next iteration begins, `--max-tokens` can abort mid-iteration once reported usage reaches the cap, and `--stop-when` ends 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
|
|
140
|
+
- **Runtime caps** - `--max-iterations` stops before the next iteration begins, `--max-tokens` can abort mid-iteration once reported usage reaches the cap, and `--stop-when` ends the loop after an iteration whose agent output reports the natural-language condition is met; resumed runs reuse the saved stop condition unless you pass a new value, or `--stop-when ""` to clear it; 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
|
|
141
|
+
- **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
|
|
142
|
+
- **Graceful interrupts** - in the interactive TUI, the first Ctrl+C requests a graceful stop and lets the current iteration finish (or ends backoff early), the second Ctrl+C force-stops immediately, and `SIGTERM` also force-stops immediately
|
|
141
143
|
- **Shared memory** — the agent reads `notes.md` (built up from prior iterations) to communicate across iterations
|
|
142
144
|
- **Local run metadata** — gnhf stores prompt, notes, and resume metadata under `.gnhf/runs/` and ignores it locally, so your branch only contains intentional work
|
|
143
145
|
- **Resume support** — run `gnhf` while on an existing `gnhf/` 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
|
|
@@ -172,10 +174,10 @@ If you run `gnhf` on an existing `gnhf/` branch with a different prompt, gnhf as
|
|
|
172
174
|
|
|
173
175
|
| Flag | Description | Default |
|
|
174
176
|
| ------------------------ | -------------------------------------------------------------------------- | ---------------------- |
|
|
175
|
-
| `--agent <agent>` | Agent to use (`claude`, `codex`, `rovodev`, or `
|
|
177
|
+
| `--agent <agent>` | Agent to use (`claude`, `codex`, `rovodev`, `opencode`, `copilot`, or `pi`) | config file (`claude`) |
|
|
176
178
|
| `--max-iterations <n>` | Abort after `n` total iterations | unlimited |
|
|
177
179
|
| `--max-tokens <n>` | Abort after `n` total input+output tokens | unlimited |
|
|
178
|
-
| `--stop-when <cond>` | End the loop when the agent reports this
|
|
180
|
+
| `--stop-when <cond>` | End the loop when the agent reports this condition; persists across resume | unlimited |
|
|
179
181
|
| `--prevent-sleep <mode>` | Prevent system sleep during the run (`on`/`off` or `true`/`false`) | config file (`on`) |
|
|
180
182
|
| `--worktree` | Run in a separate git worktree (enables multiple agents concurrently) | `false` |
|
|
181
183
|
| `--version` | Show version | |
|
|
@@ -185,13 +187,15 @@ If you run `gnhf` on an existing `gnhf/` branch with a different prompt, gnhf as
|
|
|
185
187
|
Config lives at `~/.gnhf/config.yml`:
|
|
186
188
|
|
|
187
189
|
```yaml
|
|
188
|
-
# Agent to use by default (claude, codex, rovodev, or
|
|
190
|
+
# Agent to use by default (claude, codex, rovodev, opencode, copilot, or pi)
|
|
189
191
|
agent: claude
|
|
190
192
|
|
|
191
193
|
# Custom paths to agent binaries (optional)
|
|
192
194
|
# agentPathOverride:
|
|
193
195
|
# claude: /path/to/custom-claude
|
|
194
196
|
# codex: /path/to/custom-codex
|
|
197
|
+
# copilot: /path/to/custom-copilot
|
|
198
|
+
# pi: /path/to/custom-pi
|
|
195
199
|
|
|
196
200
|
# Per-agent CLI arg overrides (optional)
|
|
197
201
|
# agentArgsOverride:
|
|
@@ -201,6 +205,16 @@ agent: claude
|
|
|
201
205
|
# - -c
|
|
202
206
|
# - model_reasoning_effort="high"
|
|
203
207
|
# - --full-auto
|
|
208
|
+
# copilot:
|
|
209
|
+
# - --model
|
|
210
|
+
# - gpt-5.4
|
|
211
|
+
# pi:
|
|
212
|
+
# - --provider
|
|
213
|
+
# - openai-codex
|
|
214
|
+
# - --model
|
|
215
|
+
# - gpt-5.5
|
|
216
|
+
# - --thinking
|
|
217
|
+
# - high
|
|
204
218
|
|
|
205
219
|
# Abort after this many consecutive failures
|
|
206
220
|
maxConsecutiveFailures: 3
|
|
@@ -212,13 +226,13 @@ preventSleep: true
|
|
|
212
226
|
If the file does not exist yet, `gnhf` creates it on first run using the resolved defaults.
|
|
213
227
|
|
|
214
228
|
CLI flags override config file values. `--prevent-sleep` accepts `on`/`off` as well as `true`/`false`; the config file always uses a boolean.
|
|
215
|
-
The iteration and token caps are runtime-only flags and are not persisted in `config.yml
|
|
229
|
+
The iteration and token caps are runtime-only flags and are not persisted in `config.yml`; `--stop-when` is persisted per run for resume, but not in config.
|
|
216
230
|
|
|
217
231
|
`agentArgsOverride.<name>` lets you pass through extra CLI flags for any supported agent.
|
|
218
232
|
|
|
219
233
|
- Use it for agent-specific options like models, profiles, or reasoning settings without adding a dedicated `gnhf` config field for each one.
|
|
220
|
-
- For `codex` and `
|
|
221
|
-
- Flags that `gnhf` manages 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.
|
|
234
|
+
- For `codex`, `claude`, and `copilot`, `gnhf` adds its usual non-interactive permission default only when you do not provide your own permission or execution-mode flag. If you set one explicitly, `gnhf` treats that as user-managed and does not add its default on top.
|
|
235
|
+
- Flags that `gnhf` manages 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. For `pi` specifically, `--api-key` is also blocked; configure the Pi API key via Pi's own config or the environment variable it reads, not via `agentArgsOverride`.
|
|
222
236
|
|
|
223
237
|
### Custom Agent Paths
|
|
224
238
|
|
|
@@ -228,6 +242,8 @@ Use `agentPathOverride` to point any agent at a custom binary — useful for wra
|
|
|
228
242
|
agentPathOverride:
|
|
229
243
|
claude: ~/bin/claude-code-switch
|
|
230
244
|
codex: /usr/local/bin/my-codex-wrapper
|
|
245
|
+
copilot: ~/bin/copilot-wrapper
|
|
246
|
+
pi: ~/bin/pi-wrapper
|
|
231
247
|
```
|
|
232
248
|
|
|
233
249
|
Paths 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 ...`.
|
|
@@ -241,14 +257,16 @@ Including a snippet of `gnhf.log` is the single most useful thing you can attach
|
|
|
241
257
|
|
|
242
258
|
## Agents
|
|
243
259
|
|
|
244
|
-
`gnhf` supports
|
|
260
|
+
`gnhf` supports six agents:
|
|
245
261
|
|
|
246
|
-
| Agent
|
|
247
|
-
|
|
|
248
|
-
| Claude Code
|
|
249
|
-
| Codex
|
|
250
|
-
|
|
|
251
|
-
|
|
|
262
|
+
| Agent | Flag | Requirements | Notes |
|
|
263
|
+
| ------------------ | ------------------ | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
264
|
+
| 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. |
|
|
265
|
+
| Codex | `--agent codex` | Install OpenAI's `codex` CLI and sign in first. | `gnhf` invokes `codex exec` directly in non-interactive mode. |
|
|
266
|
+
| GitHub Copilot CLI | `--agent copilot` | Install GitHub Copilot CLI and sign in first. | `gnhf` invokes `copilot` directly in non-interactive JSONL mode. Copilot currently exposes assistant output tokens, but not full input/cache token totals; see https://github.com/github/copilot-cli/issues/1152. |
|
|
267
|
+
| Pi | `--agent pi` | Install the `pi` CLI and configure a usable provider/model first. | `gnhf` invokes `pi` directly in JSON mode, appends the final output schema to the prompt, and disables Pi session persistence with `--no-session`. |
|
|
268
|
+
| 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. |
|
|
269
|
+
| 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. |
|
|
252
270
|
|
|
253
271
|
## Development
|
|
254
272
|
|
|
@@ -262,3 +280,13 @@ npm run test:e2e # Build, then run end-to-end tests against the mock openc
|
|
|
262
280
|
npm run lint # ESLint
|
|
263
281
|
npm run format # Prettier
|
|
264
282
|
```
|
|
283
|
+
|
|
284
|
+
## Star History
|
|
285
|
+
|
|
286
|
+
<a href="https://www.star-history.com/?repos=kunchenguid%2Fgnhf&type=date&legend=top-left">
|
|
287
|
+
<picture>
|
|
288
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=kunchenguid/gnhf&type=date&theme=dark&legend=top-left" />
|
|
289
|
+
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=kunchenguid/gnhf&type=date&legend=top-left" />
|
|
290
|
+
<img alt="Star History Chart" src="https://api.star-history.com/chart?repos=kunchenguid/gnhf&type=date&legend=top-left" />
|
|
291
|
+
</picture>
|
|
292
|
+
</a>
|