gnhf 0.1.0
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/LICENSE +21 -0
- package/README.md +156 -0
- package/dist/cli.mjs +1247 -0
- package/package.json +46 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Kun Chen
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
<h1 align="center">gnhf</h1>
|
|
2
|
+
<p align="center">
|
|
3
|
+
<a href="https://www.npmjs.com/package/gnhf"
|
|
4
|
+
><img
|
|
5
|
+
alt="npm"
|
|
6
|
+
src="https://img.shields.io/npm/v/gnhf?style=flat-square"
|
|
7
|
+
/></a>
|
|
8
|
+
<a href="https://github.com/kunchenguid/gnhf/actions/workflows/ci.yml"
|
|
9
|
+
><img
|
|
10
|
+
alt="CI"
|
|
11
|
+
src="https://img.shields.io/github/actions/workflow/status/kunchenguid/gnhf/ci.yml?style=flat-square&label=ci"
|
|
12
|
+
/></a>
|
|
13
|
+
<a href="https://github.com/kunchenguid/gnhf/actions/workflows/release-please.yml"
|
|
14
|
+
><img
|
|
15
|
+
alt="Release"
|
|
16
|
+
src="https://img.shields.io/github/actions/workflow/status/kunchenguid/gnhf/release-please.yml?style=flat-square&label=release"
|
|
17
|
+
/></a>
|
|
18
|
+
<a
|
|
19
|
+
href="https://img.shields.io/badge/platform-macOS%20%7C%20Linux-blue?style=flat-square"
|
|
20
|
+
><img
|
|
21
|
+
alt="Platform"
|
|
22
|
+
src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux-blue?style=flat-square"
|
|
23
|
+
/></a>
|
|
24
|
+
<a href="https://x.com/kunchenguid"
|
|
25
|
+
><img
|
|
26
|
+
alt="X"
|
|
27
|
+
src="https://img.shields.io/badge/X-@kunchenguid-black?style=flat-square"
|
|
28
|
+
/></a>
|
|
29
|
+
<a href="https://discord.gg/Wsy2NpnZDu"
|
|
30
|
+
><img
|
|
31
|
+
alt="Discord"
|
|
32
|
+
src="https://img.shields.io/discord/1439901831038763092?style=flat-square&label=discord"
|
|
33
|
+
/></a>
|
|
34
|
+
</p>
|
|
35
|
+
|
|
36
|
+
<h3 align="center">Before I go to bed, I tell my agents: good night, have fun.</h3>
|
|
37
|
+
|
|
38
|
+
You have a backlog of improvements you'll never get to. Tests that need writing, complexity that needs reducing, types that need fixing. You could spend a Saturday on it, or you could hand it to a coding agent and go to sleep.
|
|
39
|
+
|
|
40
|
+
gnhf is an orchestrator that runs your coding agent in a loop — each iteration makes one small, committed, documented change towards an objective. You wake up to a branch full of clean work and a log of everything that happened.
|
|
41
|
+
|
|
42
|
+
- **Set it and forget it** — one command starts an autonomous loop that runs until you Ctrl+C
|
|
43
|
+
- **Safe by design** — each iteration is committed on success, rolled back on failure, with exponential backoff and auto-abort after consecutive failures
|
|
44
|
+
- **Agent-agnostic** — works with Claude Code or Codex out of the box
|
|
45
|
+
|
|
46
|
+
## Quick Start
|
|
47
|
+
|
|
48
|
+
```sh
|
|
49
|
+
$ gnhf "reduce complexity of the codebase without changing functionality"
|
|
50
|
+
# go to sleep
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
## Install
|
|
54
|
+
|
|
55
|
+
**npm**
|
|
56
|
+
|
|
57
|
+
```sh
|
|
58
|
+
npm install -g gnhf
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
**From source**
|
|
62
|
+
|
|
63
|
+
```sh
|
|
64
|
+
git clone https://github.com/kunchenguid/gnhf.git
|
|
65
|
+
cd gnhf
|
|
66
|
+
npm install
|
|
67
|
+
npm run build
|
|
68
|
+
npm link
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
## How It Works
|
|
72
|
+
|
|
73
|
+
```
|
|
74
|
+
┌─────────────┐
|
|
75
|
+
│ gnhf start │
|
|
76
|
+
└──────┬──────┘
|
|
77
|
+
▼
|
|
78
|
+
┌──────────────────────┐
|
|
79
|
+
│ validate clean git │
|
|
80
|
+
│ create gnhf/ branch │
|
|
81
|
+
│ write prompt.md │
|
|
82
|
+
└──────────┬───────────┘
|
|
83
|
+
▼
|
|
84
|
+
┌────────────────────────────┐
|
|
85
|
+
│ build iteration prompt │◄──────────────┐
|
|
86
|
+
│ (inject notes.md context) │ │
|
|
87
|
+
└────────────┬───────────────┘ │
|
|
88
|
+
▼ │
|
|
89
|
+
┌────────────────────────────┐ │
|
|
90
|
+
│ invoke your agent │ │
|
|
91
|
+
│ (non-interactive mode) │ │
|
|
92
|
+
└────────────┬───────────────┘ │
|
|
93
|
+
▼ │
|
|
94
|
+
┌─────────────┐ │
|
|
95
|
+
│ success? │ │
|
|
96
|
+
└──┬──────┬───┘ │
|
|
97
|
+
yes │ │ no │
|
|
98
|
+
▼ ▼ │
|
|
99
|
+
┌──────────┐ ┌───────────┐ │
|
|
100
|
+
│ commit │ │ git reset │ │
|
|
101
|
+
│ append │ │ --hard │ │
|
|
102
|
+
│ notes.md │ │ backoff │ │
|
|
103
|
+
└────┬─────┘ └─────┬─────┘ │
|
|
104
|
+
│ │ │
|
|
105
|
+
│ ┌──────────┘ │
|
|
106
|
+
▼ ▼ │
|
|
107
|
+
┌────────────┐ yes ┌──────────┐ │
|
|
108
|
+
│ 5 consec. ├─────────►│ abort │ │
|
|
109
|
+
│ failures? │ └──────────┘ │
|
|
110
|
+
└─────┬──────┘ │
|
|
111
|
+
no │ │
|
|
112
|
+
└──────────────────────────────────────┘
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
- **Incremental commits** — each successful iteration is a separate git commit, so you can cherry-pick or revert individual changes
|
|
116
|
+
- **Shared memory** — the agent reads `notes.md` (built up from prior iterations) to communicate across iterations
|
|
117
|
+
- **Resume support** — run `gnhf` while on an existing `gnhf/` branch to pick up where a previous run left off
|
|
118
|
+
|
|
119
|
+
## CLI Reference
|
|
120
|
+
|
|
121
|
+
| Command | Description |
|
|
122
|
+
| ----------------------- | ----------------------------------------------- |
|
|
123
|
+
| `gnhf "<prompt>"` | Start a new run with the given objective |
|
|
124
|
+
| `gnhf` | Resume a run (when on an existing gnhf/ branch) |
|
|
125
|
+
| `echo "prompt" \| gnhf` | Pipe prompt via stdin |
|
|
126
|
+
|
|
127
|
+
### Flags
|
|
128
|
+
|
|
129
|
+
| Flag | Description | Default |
|
|
130
|
+
| ----------------- | ---------------------------------- | -------- |
|
|
131
|
+
| `--agent <agent>` | Agent to use (`claude` or `codex`) | `claude` |
|
|
132
|
+
| `--version` | Show version | |
|
|
133
|
+
|
|
134
|
+
## Configuration
|
|
135
|
+
|
|
136
|
+
Config lives at `~/.gnhf/config.yml`:
|
|
137
|
+
|
|
138
|
+
```yaml
|
|
139
|
+
# Agent to use by default
|
|
140
|
+
agent: claude
|
|
141
|
+
|
|
142
|
+
# Abort after this many consecutive failures
|
|
143
|
+
maxConsecutiveFailures: 5
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
CLI flags override config file values.
|
|
147
|
+
|
|
148
|
+
## Development
|
|
149
|
+
|
|
150
|
+
```sh
|
|
151
|
+
npm run build # Build with tsdown
|
|
152
|
+
npm run dev # Watch mode
|
|
153
|
+
npm test # Run tests (vitest)
|
|
154
|
+
npm run lint # ESLint
|
|
155
|
+
npm run format # Prettier
|
|
156
|
+
```
|