@tiens.nguyen/gu-cli 1.0.892 → 1.0.893

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.
Files changed (2) hide show
  1. package/README.md +59 -77
  2. package/package.json +2 -3
package/README.md CHANGED
@@ -1,17 +1,17 @@
1
1
  <h1 align="center">gu — the coding agent for your own models</h1>
2
2
 
3
3
  <p align="center">
4
- <strong>A coding agent in your terminal that runs on Ollama, MLX or any OpenAI-compatible API.</strong><br>
5
- It reads your repo, makes the change, runs the tests and shows you what it did. Your code stays in your folder.<br>
6
- <strong>Free for 30 days. No account, no sign-in, no card.</strong>
4
+ <strong>A coding agent in your terminal that runs on Ollama or any OpenAI-compatible API.</strong><br>
5
+ It reads your repo, makes the change, runs the tests and shows you what it did.<br>
6
+ <strong>Free installs run entirely on your machine. Free for 30 days: no account, no sign-in, no card.</strong>
7
7
  </p>
8
8
 
9
9
  <p align="center">
10
10
  <a href="https://www.npmjs.com/package/@tiens.nguyen/gu-cli"><img alt="npm" src="https://img.shields.io/npm/v/@tiens.nguyen/gu-cli?color=6366f1&label=npm"></a>
11
11
  <a href="https://www.npmjs.com/package/@tiens.nguyen/gu-cli"><img alt="downloads" src="https://img.shields.io/npm/dm/@tiens.nguyen/gu-cli?color=6366f1"></a>
12
- <img alt="node" src="https://img.shields.io/node/v/@tiens.nguyen/gu-cli?color=6366f1">
12
+ <img alt="node 20.19+" src="https://img.shields.io/badge/node-20.19%2B-6366f1">
13
13
  <img alt="platforms" src="https://img.shields.io/badge/macOS%20%C2%B7%20Linux%20%C2%B7%20Windows-supported-6366f1">
14
- <a href="./LICENSE"><img alt="license" src="https://img.shields.io/npm/l/@tiens.nguyen/gu-cli?color=6366f1"></a>
14
+ <img alt="license MIT" src="https://img.shields.io/badge/license-MIT-6366f1">
15
15
  </p>
16
16
 
17
17
  <p align="center">
@@ -37,18 +37,21 @@ gu
37
37
  ```
38
38
 
39
39
  **Free to start, no account needed.** The first run creates a free 30-day token for this
40
- computer automatically. Press Enter to use it. It also asks how this machine runs and which model
41
- provider to use. Then type what you want done.
40
+ computer. Press Enter to use it, pick a model provider, then type what you want done.
41
+
42
+ A free install is **private**: gu's API and its database (MongoDB) run on this computer, next to
43
+ your code. The first run shows what it will install and asks before installing anything.
44
+ Needs **Node.js 20.19+**.
42
45
 
43
46
  > **`gu: command not found`?** Run `npx @tiens.nguyen/gu-cli fix-path`. See [Troubleshooting](#troubleshooting).
44
47
 
45
48
  ## Why gu
46
49
 
47
- - **Your models, your choice.** Run [Ollama](https://ollama.com) or MLX on your own machine or a GPU
48
- box on your network, or bring any OpenAI-compatible provider (OpenAI, DeepSeek, OpenRouter…). Use
50
+ - **Your models, your choice.** Run [Ollama](https://ollama.com) on your own machine or a GPU box
51
+ on your network, or bring any OpenAI-compatible provider (OpenAI, DeepSeek, OpenRouter…). Use
49
52
  one model to plan and another to code; switch any time with `/model`.
50
- - **Private by default.** Logs hold no prompts, code or keys unless you run `gu --log`. Need
51
- everything in-house? Private mode runs the API and database on your own servers.
53
+ - **Private by default.** A free install keeps the agent, its API and its database on your
54
+ computer. Logs hold no prompts, code or keys unless you run `gu --log`.
52
55
  - **It proves it works.** gu runs the build and the tests and fixes what fails. For web pages, the
53
56
  `browser` tool drives a real Chrome and checks the result before gu says it is done.
54
57
  - **It stays in the repo.** Every edit is a file you can read, diff and revert; `/undo` puts back
@@ -65,16 +68,14 @@ provider to use. Then type what you want done.
65
68
  cloud, work on remote Linux boxes over SSH, or want a coding agent that costs $4 a month instead
66
69
  of a model subscription.
67
70
 
68
- **Probably not if** you want the strongest frontier model with zero setup and don't mind where your
69
- code goes: the model vendors' own agents are simpler for that. gu can still use those models
70
- through an OpenAI-compatible API, but its strength is everything else.
71
+ **Want a frontier model?** gu runs those too, through any OpenAI-compatible API, and keeps
72
+ everything else: the edits in your repo, the tests, the browser check and `/undo`.
71
73
 
72
74
  ## Quick start
73
75
 
74
76
  1. **Start gu.** Run `gu` in a project folder. Your free 30-day token is created on the spot:
75
77
  no sign-up, no browser, no card.
76
78
  2. **Check your models.** `gu doctor` sets up and tests the models on this machine.
77
- (`gu doctor --client` installs only the agent's dependencies, when the models run elsewhere.)
78
79
  3. **Ask.** Type what you want done. Conversations are saved per folder and resumed next time;
79
80
  `/new` starts a fresh one.
80
81
 
@@ -86,9 +87,10 @@ gu uses up to three models, each with its own command:
86
87
  | --- | --- | --- |
87
88
  | `/model` | **coding**: writes the code | this session (`/quick-models` keeps 2 to flip with ← / →) |
88
89
  | `/agent-model` | **agent**: talks to you and plans | this machine |
89
- | `/embed-model` | **embedding**: RAG (`nomic-embed-text`, `qwen3-embedding`), local or remote | this machine; re-indexes what was indexed |
90
+ | `/embed-model` | **embedding**: RAG (`nomic-embed-text`, `qwen3-embedding`), local or remote | this machine |
90
91
 
91
- Run `/doctor` any time to check that each one answers.
92
+ Run `/doctor` any time to check that each one answers. Coding works best with a strong model:
93
+ small local models often fail at multi-step changes.
92
94
 
93
95
  ## Using gu
94
96
 
@@ -102,10 +104,23 @@ gu [-v|--verbose] [--log] [--color] [--name <text>] [--license <pro token>]
102
104
  | `--log` | log this run in detail to `~/.gonext/worker.log` (default: starts, stops and errors only) |
103
105
  | `--color` | colour the live thought and the thinking spinner |
104
106
  | `--name <text>` | show `<text>` instead of the gu logo in the banner (this run only) |
105
- | `--license <token>` | choose a Pro licence on first install |
107
+ | `--license <token>` | use a Pro licence on first install |
106
108
 
107
109
  Ctrl-C stops the running turn. Type `/` at the prompt to see every command; Tab completes.
108
110
 
111
+ **The commands you'll use most**
112
+
113
+ | Command | What it does |
114
+ | --- | --- |
115
+ | `/model` | switch the coding model |
116
+ | `/new` | start a new conversation in this folder |
117
+ | `/undo` | put back the files the last stopped turn changed (asks first) |
118
+ | `/test-auto` | for this folder: verify and fix until the tests pass |
119
+ | `/browser` | let the agent check web pages in a real Chrome |
120
+ | `/mcp` | add MCP servers, and choose which tools run without asking |
121
+ | `/doctor` | check that every model answers |
122
+ | `/support` | send a request with gu's logs attached (secrets masked; shows you first) |
123
+
109
124
  <details>
110
125
  <summary><strong>All slash commands</strong></summary>
111
126
 
@@ -117,28 +132,24 @@ Ctrl-C stops the running turn. Type `/` at the prompt to see every command; Tab
117
132
  | `/new` | start a new conversation in this folder (the old one is archived) |
118
133
  | `/undo [runId]` | put back the files the last stopped turn changed, from its backups (asks first) |
119
134
  | `/test-auto` | toggle auto-test for this folder: verify and fix until it passes |
120
- | `/browser [allow\|forget\|install\|cleanup]` | the agent's web browser, through the gu Chrome extension or gu's own Chrome window ([guide](browser-extension/README.md)) |
135
+ | `/browser [allow\|forget\|install\|cleanup]` | the agent's web browser, through the gu Chrome extension or gu's own Chrome window |
121
136
  | `/shells` | long commands the agent left running in the background: status, output, stop one |
122
- | `/rag` | where this folder's RAG index lives: local, cloud or both |
137
+ | `/rag` | where this folder's RAG index lives |
123
138
  | `/tokens` | break down the last prompt sent to the coding model, including how much was RAG |
124
139
  | `/prices [update]` | price tables, and what the last turn and this session cost |
125
140
  | `/budget` | your API provider budgets and balances (Pro) |
126
141
  | `/mcp [list\|tools\|add\|remove\|enable\|disable\|approve\|allow\|disallow\|reconnect]` | MCP servers, and which of their tools run without asking |
127
142
  | `/hooks [list\|approve\|unapprove]` | commands gu runs on `onStart`, `onAsk`, `onToolDone`, `onTurnEnd` |
128
143
  | `/switch-skill [claude\|gu]` | use Claude Code's (`.claude`) or gu's (`.gonext`) skills, MCP servers and hooks in this folder |
129
- | `/skill-pack <name> [--out <file>] [--runtime <dir>]` | pack a skill with its MCP servers, hooks and code into one zip for another machine (no venvs, databases or secrets) |
130
- | `/skill-install <zip\|folder> [--gu] [--claude] [--dry-run]` | install a packed skill for gu and Claude Code; without gu: `node <name>/install.mjs` |
131
- | `/resume` | carry on the last unfinished task in this folder, Claude Code's or gu's: shows its plan, last command and next step, then asks (needs the memory skill) |
132
- | `/skills-copy-to-claude [--dry-run] [name…]` | copy gu's skills into Claude Code's folders |
144
+ | `/skill-pack <name>`, `/skill-install <zip\|folder>` | pack a skill with its MCP servers and hooks into one zip, and install it on another machine (no secrets) |
145
+ | `/resume` | carry on the last unfinished task in this folder, Claude Code's or gu's |
133
146
  | `/proxy [show\|set\|on\|off\|clear\|test]` | route model calls through an HTTP proxy (local calls go direct) |
134
147
  | `/s3 [test]` | use your own S3 bucket for the RAG index and generated files |
135
- | `/server` | pick a deployment server (host/user) for this session |
136
- | `/host-mode` | undo client mode: run agent turns on this machine again |
137
148
  | `/save-settings`, `/load-settings` | move providers, models and key *names* (no secrets) to another machine |
138
149
  | `/save-preset`, `/open-presets`, `/use-presets` | your whole setup, keys included, to copy, edit and apply (backs up first) |
139
- | `/clear-logs` | show what logs, RAG indexes and old API versions take on disk, then ask what to clear |
140
- | `/voucher CODE` | use a voucher code: adds free days to this computer's trial or your free account |
141
- | `/support` | send the support team a request with gu's logs attached (secrets masked; shows what goes first) |
150
+ | `/clear-logs` | show what logs and indexes take on disk, then ask what to clear |
151
+ | `/voucher CODE` | add free days to this computer's trial or your free account |
152
+ | `/support` | send the support team a request with gu's logs attached |
142
153
  | `/help`, `/exit` | list commands / quit |
143
154
 
144
155
  Each skill in `~/.gonext/skills/<name>/SKILL.md` (or the folder's `.gonext/skills`) is a slash command too.
@@ -149,32 +160,25 @@ Each skill in `~/.gonext/skills/<name>/SKILL.md` (or the folder's `.gonext/skill
149
160
  <summary><strong>Shell commands</strong></summary>
150
161
 
151
162
  ```
152
- gu status worker status and the running model servers
153
- gu start | stop | restart the background worker (stop --models: model servers too)
154
- gu logs [--lines N] [-f] tail the worker log; gu logs <port|pid|chat|embed> for a model server
155
- gu doctor [--client] set up and check models on this machine
156
- gu rag [plan [path] | --test] test the embedder, list knowledge bases, estimate index time
157
- gu api <start|stop|restart|status|upgrade> the local API (private machines)
163
+ gu status is gu running, and which model servers
164
+ gu start | stop | restart the background worker
165
+ gu logs [--lines N] [-f] follow gu's log
166
+ gu doctor set up and check models on this machine
167
+ gu rag [plan [path] | --test] test the embedder, estimate index time
158
168
  gu workspace revert [runId] undo an agent run's file edits from its backups
159
169
  gu support send a support request with masked logs
160
- gu test-proxy check model calls through a proxy
161
- gu mongo migrate-from-docker macOS: move a Docker MongoDB to Homebrew
162
- gu clear [--scratch|--keep-history] [--yes] back to a fresh machine (asks first)
170
+ gu clear [--yes] back to a fresh machine (asks first)
163
171
  gu fix-path | fix-powershell repair PATH / remove PowerShell's `gu` alias
164
172
  ```
165
173
 
166
- `gu-cli` takes the same commands, plus `login [--api-base <url>]`, `set <workerKey>`,
167
- `token [<token>]`, `ws-ping-test` and `simulate-chat [text…]`.
168
-
169
174
  </details>
170
175
 
171
176
  ## Where gu keeps things
172
177
 
173
178
  | Path | Contents |
174
179
  | --- | --- |
175
- | `~/.gonext/worker.env` | sign-in: worker key and API address |
176
180
  | `~/.gonext/sessions/` | conversation history per folder (`archive/` holds old ones) |
177
- | `~/.gonext/worker.log`, `~/.gonext/local-api.log` | logs |
181
+ | `~/.gonext/worker.log` | log |
178
182
  | `~/.gonext/mcp.json` | MCP servers and their allow rules |
179
183
  | `~/.gonext/skills/`, `<folder>/.gonext/skills/` | skills: everywhere / this folder only |
180
184
 
@@ -182,57 +186,35 @@ gu fix-path | fix-powershell repair PATH / remove PowerShell's `gu` alias
182
186
 
183
187
  | | How long | What you need |
184
188
  | --- | --- | --- |
185
- | **Free trial** | 30 days, starts on the first run | nothing: the token is created for you |
189
+ | **Free trial** | 30 days, from the first run | nothing: the token is created for you |
186
190
  | **Free plan** | 3 more months on that computer | a free account at [gucli.com](https://gucli.com) |
187
- | **Pro** | while subscribed: **$4 a month** (110.000 ₫) + VAT, or $40 a year | the hosted agent and coder (no model server to run), up to 5 computers, provider budgets |
191
+ | **Pro** | **$4 a month** or **$40 a year** (+ VAT where it applies) | hosted models (no model server to run), up to 5 computers, provider budgets |
192
+
193
+ On Pro, the hosted models and the hosted API run on gu's servers, so the prompts and code you
194
+ send through them go there. A free install keeps everything on your computer.
188
195
 
189
196
  Got a **voucher code**? Type `/voucher CODE` in gu (or enter it on your
190
- [account page](https://gucli.com/account)) for extra free days on top.
197
+ [account page](https://gucli.com/account)) for extra free days.
191
198
 
192
199
  Free time belongs to the computer: reinstalling doesn't restart it. Already have a token? Paste
193
- it at the first-run question instead, or later with `gu-cli token <token>`. Current prices: [gucli.com/pricing](https://gucli.com/pricing).
200
+ it at the first-run question. Current prices: [gucli.com/pricing](https://gucli.com/pricing).
194
201
 
195
202
  ## Troubleshooting
196
203
 
197
204
  **`gu: command not found` after install.** npm 11 skips install scripts it wasn't told to allow,
198
205
  so the step that adds npm's bin folder to your PATH may not have run. Run
199
206
  `npx @tiens.nguyen/gu-cli fix-path`. It also finds what an old install left behind (broken links,
200
- a second gu from another npm, a PATH line pinned to an old Homebrew folder) and asks before
201
- fixing each one. `--check` only reports.
207
+ a second gu from another npm, a stale PATH line) and asks before fixing each one. `--check` only reports.
202
208
 
203
209
  **Windows: `gu` runs `Get-Unique`.** PowerShell has a built-in `gu` alias. Run `gu-cli fix-powershell`.
204
210
 
205
- **Node version.** Node.js 18+ runs the CLI. A private machine (API and database on this
206
- computer) needs **Node.js 20.19+**.
211
+ **Node version.** gu needs **Node.js 20.19+** (a Pro install using only hosted models runs on 18+).
207
212
 
208
213
  **A change in a model or setting seems ignored.** `gu doctor` shows the model and URL actually in use.
209
214
 
210
- **Still stuck?** Run `gu support` (or `/support` in gu, or click **? support** in the footer). It
211
- sends the team your request with gu's logs attached, secrets masked, and shows you what goes
212
- before sending.
213
-
214
- <details>
215
- <summary><strong>Advanced: worker jobs and environment variables</strong></summary>
216
-
217
- The background worker also runs jobs queued from the [web app](https://gucli.com) on this machine:
218
-
219
- - **Agent chat**: choosing **Agent** in the web app runs a
220
- [smolagents](https://github.com/huggingface/smolagents) agent on your local model
221
- (`pip install smolagents certifi`). Cloud models are not allowed here; pick a local MLX or Ollama model.
222
- - **API checks**: the worker makes the HTTP request itself, measures status, latency and body,
223
- and a local model writes a one-line summary.
224
-
225
- | Variable | Meaning |
226
- | --- | --- |
227
- | `GONEXT_API_BASE`, `GONEXT_WORKER_KEY` | API address and worker key (normally from `~/.gonext/worker.env`) |
228
- | `GONEXT_PROBE_PYTHON` | Python for agent scripts (default: `GONEXT_MLX_LM_PYTHON` or `python3`) |
229
- | `GONEXT_MLX_LM_PYTHON` | Python for the MLX probe (default `python3`) |
230
- | `GONEXT_OCR_MODEL_PATH` | local GLM-OCR directory (default `~/mlx-models/GLM-OCR-bf16`) |
231
- | `GONEXT_OCR_DEBUG=1` | print raw OCR output |
232
- | `GONEXT_SIMULATE_TEXT` | default reply for `simulate-chat` |
233
-
234
- </details>
215
+ **Still stuck?** Run `gu support` (or `/support` in gu). It sends the team your request with gu's
216
+ logs attached, secrets masked, and shows you what goes before sending.
235
217
 
236
218
  ## License
237
219
 
238
- [MIT](./LICENSE) © Tien Nguyen Song
220
+ MIT © Tien Nguyen Song
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@tiens.nguyen/gu-cli",
3
- "version": "1.0.892",
4
- "description": "gu: the coding agent in your terminal. It reads your repo, makes the change and runs the tests, with your own models (Ollama, MLX or any OpenAI-compatible provider). macOS, Linux and Windows.",
3
+ "version": "1.0.893",
4
+ "description": "gu: the coding agent in your terminal. It reads your repo, makes the change and runs the tests, with your own models (Ollama or any OpenAI-compatible provider). Free installs run entirely on your machine. macOS, Linux and Windows.",
5
5
  "keywords": [
6
6
  "ai",
7
7
  "coding-agent",
@@ -9,7 +9,6 @@
9
9
  "terminal",
10
10
  "llm",
11
11
  "ollama",
12
- "mlx",
13
12
  "openai",
14
13
  "agent",
15
14
  "mcp",