gnhf 0.1.29 → 0.1.31
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 +57 -30
- package/dist/cli.mjs +13168 -235
- package/package.json +5 -3
package/README.md
CHANGED
|
@@ -46,8 +46,8 @@ You wake up to a branch full of clean work and a log of everything that happened
|
|
|
46
46
|
|
|
47
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; retryable hard agent errors back off exponentially while agent-reported failures continue immediately
|
|
49
|
-
- **Live terminal title** — interactive runs keep your terminal title updated with live status, token totals, and commit count, then restore
|
|
50
|
-
- **Agent-agnostic**: works with Claude Code, Codex, Rovo Dev, OpenCode, GitHub Copilot CLI, or
|
|
49
|
+
- **Live terminal title** — interactive runs keep your terminal title updated with live status, token totals, and commit count, then clear or restore it on exit depending on terminal support; token totals prefixed with `~` are estimates
|
|
50
|
+
- **Agent-agnostic**: works with Claude Code, Codex, Rovo Dev, OpenCode, GitHub Copilot CLI, Pi, or ACP targets out of the box
|
|
51
51
|
|
|
52
52
|
## Quick Start
|
|
53
53
|
|
|
@@ -137,14 +137,14 @@ npm link
|
|
|
137
137
|
└──────────────────────────────────────┘
|
|
138
138
|
```
|
|
139
139
|
|
|
140
|
-
- **Incremental commits**
|
|
141
|
-
- **Failure handling** - all failed iterations are rolled back with `git reset --hard`; agent-reported failures proceed to the next iteration immediately, retryable hard agent errors use exponential backoff, and permanent agent errors such as Claude low credit balance abort immediately and print the run log path
|
|
140
|
+
- **Incremental commits** - each successful iteration is a separate unsigned git commit, so you can cherry-pick or revert individual changes without GPG or SSH signing prompts blocking the run
|
|
141
|
+
- **Failure handling** - all failed iterations are rolled back with `git reset --hard`; agent-reported failures proceed to the next iteration immediately, retryable hard agent errors use exponential backoff, and permanent agent errors such as Claude low credit balance abort immediately and print the run log path. Complete no-op iterations are reported as failures and count toward the consecutive-failure abort limit.
|
|
142
142
|
- **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
|
|
143
143
|
- **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
|
|
144
144
|
- **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
|
|
145
145
|
- **Shared memory** — the agent reads `notes.md` (built up from prior iterations) to communicate across iterations
|
|
146
|
-
- **Local run metadata** — gnhf stores prompt, notes, and
|
|
147
|
-
- **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
|
|
146
|
+
- **Local run metadata** — gnhf stores prompt, notes, stop conditions, and commit-message convention metadata under `.gnhf/runs/` and ignores it locally, so your branch only contains intentional work
|
|
147
|
+
- **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. New runs whose generated branch already exists use a numeric suffix such as `gnhf/<slug>-1`.
|
|
148
148
|
|
|
149
149
|
### Worktree Mode
|
|
150
150
|
|
|
@@ -158,6 +158,7 @@ Pass `--worktree` to run each agent in an isolated [git worktree](https://git-sc
|
|
|
158
158
|
```
|
|
159
159
|
|
|
160
160
|
- Worktrees with commits are **preserved** after the run so you can review, merge, or cherry-pick the work. gnhf prints the path and cleanup command.
|
|
161
|
+
- Re-running the same prompt with `--worktree` resumes a preserved matching worktree when possible; otherwise gnhf creates a suffixed worktree such as `<run-slug>-1` if the original name is unavailable.
|
|
161
162
|
- Worktrees with **no commits** are automatically removed on exit.
|
|
162
163
|
- `--worktree` must be run from a non-gnhf branch (typically `main`).
|
|
163
164
|
|
|
@@ -174,32 +175,32 @@ If you run `gnhf` on an existing `gnhf/` branch with a different prompt, gnhf as
|
|
|
174
175
|
|
|
175
176
|
### Flags
|
|
176
177
|
|
|
177
|
-
| Flag | Description
|
|
178
|
-
| ------------------------ |
|
|
179
|
-
| `--agent <agent>` | Agent to use (`claude`, `codex`, `rovodev`, `opencode`, `copilot`, or `
|
|
180
|
-
| `--max-iterations <n>` | Abort after `n` total iterations
|
|
181
|
-
| `--max-tokens <n>` | Abort after `n` total input+output tokens
|
|
182
|
-
| `--stop-when <cond>` | End the loop when the agent reports this condition; persists across resume
|
|
183
|
-
| `--prevent-sleep <mode>` | Prevent system sleep during the run (`on`/`off` or `true`/`false`)
|
|
184
|
-
| `--worktree` | Run in a separate git worktree (enables multiple agents concurrently)
|
|
185
|
-
| `--version` | Show version
|
|
178
|
+
| Flag | Description | Default |
|
|
179
|
+
| ------------------------ | ------------------------------------------------------------------------------------------- | ---------------------- |
|
|
180
|
+
| `--agent <agent>` | Agent to use (`claude`, `codex`, `rovodev`, `opencode`, `copilot`, `pi`, or `acp:<target>`) | config file (`claude`) |
|
|
181
|
+
| `--max-iterations <n>` | Abort after `n` total iterations | unlimited |
|
|
182
|
+
| `--max-tokens <n>` | Abort after `n` total input+output tokens | unlimited |
|
|
183
|
+
| `--stop-when <cond>` | End the loop when the agent reports this condition; persists across resume | unlimited |
|
|
184
|
+
| `--prevent-sleep <mode>` | Prevent system sleep during the run (`on`/`off` or `true`/`false`) | config file (`on`) |
|
|
185
|
+
| `--worktree` | Run in a separate git worktree (enables multiple agents concurrently) | `false` |
|
|
186
|
+
| `--version` | Show version | |
|
|
186
187
|
|
|
187
188
|
## Configuration
|
|
188
189
|
|
|
189
190
|
Config lives at `~/.gnhf/config.yml`:
|
|
190
191
|
|
|
191
192
|
```yaml
|
|
192
|
-
# Agent to use by default (claude, codex, rovodev, opencode, copilot, or
|
|
193
|
+
# Agent to use by default (claude, codex, rovodev, opencode, copilot, pi, or acp:<target>)
|
|
193
194
|
agent: claude
|
|
194
195
|
|
|
195
|
-
# Custom paths to agent binaries (optional)
|
|
196
|
+
# Custom paths to native agent binaries (optional)
|
|
196
197
|
# agentPathOverride:
|
|
197
198
|
# claude: /path/to/custom-claude
|
|
198
199
|
# codex: /path/to/custom-codex
|
|
199
200
|
# copilot: /path/to/custom-copilot
|
|
200
201
|
# pi: /path/to/custom-pi
|
|
201
202
|
|
|
202
|
-
#
|
|
203
|
+
# Native agent CLI arg overrides (optional)
|
|
203
204
|
# agentArgsOverride:
|
|
204
205
|
# codex:
|
|
205
206
|
# - -m
|
|
@@ -218,6 +219,17 @@ agent: claude
|
|
|
218
219
|
# - --thinking
|
|
219
220
|
# - high
|
|
220
221
|
|
|
222
|
+
# Custom ACP target commands (optional)
|
|
223
|
+
# acpRegistryOverrides:
|
|
224
|
+
# my-fork: "/usr/local/bin/my-claude-code-fork --acp"
|
|
225
|
+
# staging: "node /opt/staging/agent.mjs"
|
|
226
|
+
|
|
227
|
+
# Commit message convention (optional)
|
|
228
|
+
# Defaults to: gnhf #<iteration>: <summary>
|
|
229
|
+
# Use the conventional preset for semantic-release compatible headers:
|
|
230
|
+
# commitMessage:
|
|
231
|
+
# preset: conventional
|
|
232
|
+
|
|
221
233
|
# Abort after this many consecutive failures
|
|
222
234
|
maxConsecutiveFailures: 3
|
|
223
235
|
|
|
@@ -230,15 +242,23 @@ If the file does not exist yet, `gnhf` creates it on first run using the resolve
|
|
|
230
242
|
CLI flags override config file values. `--prevent-sleep` accepts `on`/`off` as well as `true`/`false`; the config file always uses a boolean.
|
|
231
243
|
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.
|
|
232
244
|
|
|
233
|
-
`agentArgsOverride.<name>` lets you pass through extra CLI flags for
|
|
245
|
+
`agentArgsOverride.<name>` lets you pass through extra CLI flags for native agents (`claude`, `codex`, `rovodev`, `opencode`, `copilot`, or `pi`).
|
|
246
|
+
ACP targets do not support path or arg overrides in this version.
|
|
247
|
+
Use `acpRegistryOverrides` to map `acp:<target>` names to custom spawn commands for local, forked, or beta ACP agents.
|
|
234
248
|
|
|
235
249
|
- Use it for agent-specific options like models, profiles, or reasoning settings without adding a dedicated `gnhf` config field for each one.
|
|
236
250
|
- 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.
|
|
237
251
|
- 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`.
|
|
238
252
|
|
|
253
|
+
`commitMessage` controls the subject line that gnhf uses for each successful iteration commit.
|
|
254
|
+
|
|
255
|
+
- Omit it to keep the default `gnhf #<iteration>: <summary>` format.
|
|
256
|
+
- Set `preset: conventional` to ask the agent for `type` and optional `scope`, then commit as `type(scope): summary` for semantic-release style workflows. Valid types are `build`, `ci`, `docs`, `feat`, `fix`, `perf`, `refactor`, `test`, and `chore`; invalid or missing types fall back to `chore`, and empty scopes are omitted.
|
|
257
|
+
- The resolved commit-message convention is saved per run, so resuming a `gnhf/` branch keeps the original subject format even if `config.yml` changes later.
|
|
258
|
+
|
|
239
259
|
### Custom Agent Paths
|
|
240
260
|
|
|
241
|
-
Use `agentPathOverride` to point any agent at a custom binary
|
|
261
|
+
Use `agentPathOverride` to point any native agent at a custom binary - useful for wrappers like Claude Code Switch or custom Codex builds that accept the same flags and arguments as the original:
|
|
242
262
|
|
|
243
263
|
```yaml
|
|
244
264
|
agentPathOverride:
|
|
@@ -257,18 +277,25 @@ Every run writes a JSONL debug log to `.gnhf/runs/<runId>/gnhf.log` alongside `n
|
|
|
257
277
|
|
|
258
278
|
Including a snippet of `gnhf.log` is the single most useful thing you can attach when filing an issue.
|
|
259
279
|
|
|
280
|
+
## Telemetry
|
|
281
|
+
|
|
282
|
+
`gnhf` sends anonymous usage telemetry to my self-hosted analytics so I can see what's actually getting used.
|
|
283
|
+
No prompts, repo paths, or branch names are sent.
|
|
284
|
+
Set `GNHF_TELEMETRY=0` to turn it off.
|
|
285
|
+
|
|
260
286
|
## Agents
|
|
261
287
|
|
|
262
|
-
`gnhf` supports six agents
|
|
288
|
+
`gnhf` supports six native agents plus ACP targets. ACP support is powered by [`acpx`](https://github.com/openclaw/acpx), which is bundled with `gnhf` and provides the runtime and agent registry for `acp:<target>` specs.
|
|
263
289
|
|
|
264
|
-
| Agent | Flag
|
|
265
|
-
| ------------------ |
|
|
266
|
-
| Claude Code | `--agent claude`
|
|
267
|
-
| Codex | `--agent codex`
|
|
268
|
-
| GitHub Copilot CLI | `--agent copilot`
|
|
269
|
-
| Pi | `--agent pi`
|
|
270
|
-
| Rovo Dev | `--agent rovodev`
|
|
271
|
-
| OpenCode | `--agent opencode`
|
|
290
|
+
| Agent | Flag | Requirements | Notes |
|
|
291
|
+
| ------------------ | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
292
|
+
| 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. |
|
|
293
|
+
| Codex | `--agent codex` | Install OpenAI's `codex` CLI and sign in first. | `gnhf` invokes `codex exec` directly in non-interactive mode. |
|
|
294
|
+
| 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. |
|
|
295
|
+
| 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`. |
|
|
296
|
+
| 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. |
|
|
297
|
+
| 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. |
|
|
298
|
+
| ACP target | `--agent acp:<target>` | Install and authenticate the target supported by the bundled [`acpx`](https://github.com/openclaw/acpx) registry, such as `acp:gemini`. | `gnhf` runs the target through ACP with a persistent per-run session under `.gnhf/runs/<runId>/acp-sessions`; token usage and `--max-tokens` use ACP `used` deltas when available, with prompt-length plus tool-call estimates as a fallback, and `agentPathOverride` and `agentArgsOverride` do not apply. |
|
|
272
299
|
|
|
273
300
|
## Development
|
|
274
301
|
|
|
@@ -277,7 +304,7 @@ If you want to contribute changes back to this repo, see [`CONTRIBUTING.md`](./C
|
|
|
277
304
|
```sh
|
|
278
305
|
npm run build # Build with tsdown
|
|
279
306
|
npm run dev # Watch mode
|
|
280
|
-
npm test # Build, then run
|
|
307
|
+
npm test # Build, then run all tests (vitest)
|
|
281
308
|
npm run test:e2e # Build, then run end-to-end tests against the mock opencode executable
|
|
282
309
|
npm run lint # ESLint
|
|
283
310
|
npm run format # Prettier
|