nex-code 0.4.40 → 0.5.1

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 (5) hide show
  1. package/README.md +181 -1487
  2. package/dist/benchmark.js +524 -431
  3. package/dist/nex-code.js +831 -738
  4. package/dist/skills/autoresearch.js +11 -11
  5. package/package.json +10 -4
package/README.md CHANGED
@@ -10,7 +10,7 @@
10
10
  </p>
11
11
 
12
12
  <p align="center">
13
- <a href="https://github.com/hybridpicker/nex-code/stargazers">⭐ If this saves you time, a star helps others find it.</a>
13
+ <a href="https://github.com/hybridpicker/nex-code/stargazers">If this saves you time, a star helps others find it.</a>
14
14
  </p>
15
15
 
16
16
  <p align="center">
@@ -22,24 +22,14 @@
22
22
  <img src="https://img.shields.io/badge/Ollama_Cloud-supported-brightgreen.svg" alt="Ollama Cloud: supported">
23
23
  <img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg" alt="Node >= 18">
24
24
  <img src="https://img.shields.io/badge/dependencies-2-green.svg" alt="Dependencies: 2">
25
- <img src="https://img.shields.io/badge/tests-3719-blue.svg" alt="Tests: 3719">
25
+ <img src="https://img.shields.io/badge/tests-3920-blue.svg" alt="Tests: 3920">
26
26
  <img src="https://img.shields.io/badge/VS_Code-extension-007ACC.svg" alt="VS Code extension">
27
27
  </p>
28
28
 
29
29
  ---
30
30
 
31
- ```
32
- ██▄▄██ nex-code v0.3.54
33
- █▀██▀█ devstral-2:123b · /help
34
- ▀████▀
35
- ```
36
-
37
- ---
38
-
39
31
  ## Demo
40
32
 
41
-
42
-
43
33
  https://github.com/user-attachments/assets/68a6c134-2d13-4d66-bc5e-befea3acb794
44
34
 
45
35
  ---
@@ -48,232 +38,93 @@ https://github.com/user-attachments/assets/68a6c134-2d13-4d66-bc5e-befea3acb794
48
38
 
49
39
  ```bash
50
40
  npx nex-code
41
+ # or install globally:
42
+ npm install -g nex-code && cd ~/your-project && nex-code
51
43
  ```
52
44
 
53
- Or install globally:
54
-
55
- ```bash
56
- npm install -g nex-code
57
- cd ~/your-project
58
- nex-code
59
- ```
60
-
61
- That's it. You'll see the banner, your project context, and the `>` prompt. Start typing.
62
-
63
- ---
64
-
65
- ## Automatic Updates
66
-
67
- Nex Code automatically checks for new versions when you start it. If a newer version is available, you'll see a notification with instructions on how to update:
68
-
69
- ```
70
- 💡 New version available! Run npm update -g nex-code to upgrade from x.x.x to x.x.x
71
- ```
72
-
73
- To update to the latest version:
74
-
75
- ```bash
76
- npm update -g nex-code
77
- ```
45
+ On first launch, an interactive setup wizard guides you through provider and credential configuration. Re-run anytime with `/setup`.
78
46
 
79
47
  ---
80
48
 
81
49
  ## Why nex-code?
82
50
 
51
+ **Ollama Cloud first.** Built and optimized for [Ollama Cloud](https://ollama.com) — the flat-rate platform running devstral, Kimi K2, Qwen3-Coder, and 47+ models. Other providers (OpenAI, Anthropic, Gemini) work via the same interface.
52
+
83
53
  | Feature | nex-code | Closed-source alternatives |
84
54
  |---|---|---|
85
- | Free tier | ✅ Ollama Cloud flat-rate | ❌ subscription or limited quota |
86
- | Open models | ✅ devstral, Kimi K2, Qwen3 | ❌ vendor-locked |
87
- | Local Ollama | ✅ | ❌ |
88
- | Multi-provider | ✅ swap with one env var | ❌ |
89
- | VS Code sidebar | ✅ built-in | partial |
90
- | Startup time | ~100ms | 1–4s |
91
- | Runtime deps | 2 | heavy | heavy |
92
- | Infra tools | ✅ SSH, Docker, K8s built-in | ❌ | ❌ |
93
-
94
- ---
95
-
96
- ## Why nex-code?
97
-
98
- **Ollama Cloud first.** nex-code is built and optimized for [Ollama Cloud](https://ollama.com) — the flat-rate platform that runs devstral, Kimi K2, Qwen3-Coder, and 47+ other open models. All behavioral tuning (loop detection, context compression, tool-call repair) is done against real Ollama Cloud sessions. Other providers (OpenAI, Anthropic, Gemini) work via the same interface but are not the primary target.
55
+ | Free tier | Ollama Cloud flat-rate | subscription or limited quota |
56
+ | Open models | devstral, Kimi K2, Qwen3 | vendor-locked |
57
+ | Local Ollama | yes | no |
58
+ | Multi-provider | swap with one env var | no |
59
+ | VS Code sidebar | built-in | partial |
60
+ | Startup time | ~100ms | 1-4s |
61
+ | Runtime deps | 2 | heavy |
62
+ | Infra tools | SSH, Docker, K8s built-in | no |
99
63
 
100
- **Recommended model: `devstral-2:123b`** — purpose-built for agentic coding, highest score on nex-code's own benchmark, best tool-call reliability.
64
+ **Smart model routing.** The built-in `/benchmark` tests all configured models across 62 tool-calling tasks in 5 categories and auto-routes to the best model per task type.
101
65
 
102
- **Open-model first.** Not locked to any single vendor. Tool tiers (`essential / standard / full`) adapt automatically to the model's capability level, so smaller models don't receive tool schemas they can't handle. A 5-layer auto-fix loop catches and retries malformed tool calls without user intervention.
66
+ **Phase-based execution.** Tasks run through Plan (analyze) -> Implement (code) -> Verify (test) phases, each with the optimal model. Auto-loops back on test failures.
103
67
 
104
- **Smart model routing.** The built-in `/benchmark` system tests all configured models against 62 real nex-code tool-calling tasks across 5 task categories. The results feed a routing table so nex-code can automatically switch to the best model for the detected task type:
68
+ **45 built-in tools** across file ops, git, SSH, Docker, Kubernetes, deploy, browser, GitHub Actions, and visual review.
105
69
 
106
- | Detected task | Routed model (example) |
107
- | ------------------------- | --------------------------- |
108
- | Frontend / CSS / React | `qwen3-coder:480b` |
109
- | Sysadmin / Docker / nginx | `devstral-2:123b` |
110
- | Data / SQL / migrations | `devstral-2:123b` |
111
- | Agentic swarms | `minimax-m2.7:cloud` |
112
- | General coding | `devstral-2:123b` (default) |
113
-
114
- **Phase-based execution.** On Ollama Cloud, each task automatically runs through three phases — each with the optimal model:
115
-
116
- | Phase | Purpose | Default model |
117
- | ------------- | -------------------------------- | ------------------------ |
118
- | **Plan** | Analyze codebase, find root cause | `qwen3-coder:480b` |
119
- | **Implement** | Write code, edit files | active model (default) |
120
- | **Verify** | Run tests, check correctness | `devstral-small-2:24b` |
121
-
122
- The verify phase catches incomplete work before reporting "done" — if tests fail, it loops back to implement automatically. Phase models are auto-updated by `/benchmark`. Disable with `NEX_PHASE_ROUTING=0`.
123
-
124
- **Built-in VS Code extension.** A sidebar chat panel with streaming output, collapsible tool cards, and native VS Code theme support — shipped in the same repo, no separate install.
125
-
126
- **Lightweight.** 2 runtime dependencies (`axios`, `dotenv`). Starts in ~100ms. No Python, no heavy runtime, no daemon process.
127
-
128
- **Server-aware from the first message.** When your prompt contains a URL whose domain matches a configured SSH profile (e.g. `server.example.com` → profile `server`), nex-code probes the server before responding — listing ports, running processes, and data directories. The model receives this topology before its first token, so it goes straight to `ssh_exec` instead of reading local files.
129
-
130
- **Few-shot behavior injection.** On each session start, nex-code injects a short example of the correct tool sequence for the detected task type (sysadmin → check remote logs first; coding → read file before editing; data → explain before rewriting). Works across all models without fine-tuning. Customize with your own high-scoring sessions via `npm run extract-examples`.
131
-
132
- **Infrastructure tools built in:**
133
-
134
- - SSH server management (AlmaLinux, macOS, any Linux)
135
- - Docker tools — local and remote via SSH
136
- - Kubernetes overview (`/k8s`)
137
- - GitHub Actions tools (trigger, monitor runs)
138
- - Named deploy configs (`rsync`-based, `/deploy`)
139
- - Browser agent via Playwright (optional, not bundled)
140
- - Grounded web search via Perplexity or DuckDuckGo
141
-
142
- **Developer safety:**
143
-
144
- - Pre-push secret detection — blocks commits that contain API keys or tokens
145
- - Full audit log (JSONL + sanitization)
146
- - Undo/Redo with persistence across restarts
147
- - Cost tracking and per-provider budget limits
148
- - Plan mode — analysis-only pass before any file changes
149
-
150
- **Extensible.** Plugin API (`registerTool` + lifecycle hooks), skill system (install from any git URL), MCP server support.
151
-
152
- **Tested.** 3719 tests, 83% coverage, CI on every push.
70
+ **2 runtime dependencies** (`axios`, `dotenv`). Starts in ~100ms. No Python, no heavy runtime.
153
71
 
154
72
  ---
155
73
 
156
- ## Ollama Cloud — Recommended Model Setup
157
-
158
- nex-code was built with Ollama Cloud as its primary provider. No subscription, no billing surprises.
159
- Rankings are based on nex-code's own `/benchmark` — 14-task quick benchmark against real nex-code schemas (62 tasks full run).
74
+ ## Ollama Cloud Model Rankings
160
75
 
161
- ### Flat-Rate / Pay-as-you-go
76
+ Rankings from nex-code's own `/benchmark` — 62 tasks testing tool selection, argument validity, and schema compliance.
162
77
 
163
78
  <!-- nex-benchmark-start -->
164
79
  <!-- Updated: 2026-04-01 — run `/benchmark --discover` after new Ollama Cloud releases -->
165
80
 
166
- | Rank | Model | Score | Avg Latency | Context | Best For |
81
+ | Rank | Model | Score | Latency | Context | Best For |
167
82
  |---|---|---|---|---|---|
168
- | 🥇 | `qwen3-vl:235b-instruct` | **79.9** | 3.8s | 131K | Best latency/score balance — recommended default |
169
- | 🥈 | `qwen3-vl:235b` | 79.4 | 12.3s | 131K | Overall #1 — frontier tool selection, data + agentic tasks |
170
- | 🥉 | `qwen3-coder-next` | 74.9 | 1.7s | 256K | — |
171
- | — | `rnj-1:8b` | 74.6 | 2.5s | 131K | — |
172
- | — | `ministral-3:8b` | 74.2 | 1.2s | 131K | Fastest strong model — 2.2s latency, 70+ score |
173
- | — | `qwen3.5:397b` | 72.8 | 2.1s | 256K | — |
174
- | — | `qwen3-next:80b` | 71.3 | 10.3s | 131K | — |
175
- | — | `devstral-2:123b` | 69.9 | 1.6s | 131K | Sysadmin + SSH tasks, reliable coding |
176
- | — | `minimax-m2.7` | 69.4 | 4.1s | 200K | — |
177
- | — | `glm-5` | 69 | 7.6s | 131K | — |
178
- | — | `glm-4.7` | 67.8 | 3.7s | 131K | — |
179
- | — | `kimi-k2-thinking` | 62 | 2.4s | 256K | — |
180
-
181
- > Rankings are nex-code-specific: tool name accuracy, argument validity, schema compliance.
182
- > Toolathon (Minimax SOTA) measures different task types — run `/benchmark --discover` after model releases.
83
+ | 1 | `qwen3-vl:235b-instruct` | **79.9** | 3.8s | 131K | Best latency/score balance |
84
+ | 2 | `qwen3-vl:235b` | 79.4 | 12.3s | 131K | Frontier tool selection |
85
+ | 3 | `qwen3-coder-next` | 74.9 | 1.7s | 256K | — |
86
+ | 4 | `ministral-3:8b` | 74.2 | 1.2s | 131K | Fastest strong model |
87
+ | 5 | `devstral-2:123b` | 69.9 | 1.6s | 131K | Sysadmin/SSH, reliable |
88
+
89
+ > Run `/benchmark --discover` to detect new models and auto-update this table.
183
90
  <!-- nex-benchmark-end -->
184
91
 
185
- ### Recommended `.env` for Ollama Cloud (Flat-Rate)
92
+ **Recommended `.env`:**
186
93
 
187
94
  ```env
188
95
  DEFAULT_PROVIDER=ollama
189
- DEFAULT_MODEL=devstral-2:123b # nex-code benchmark winner (84/100, 1.5s)
190
-
191
- # Sub-agent routing
192
- NEX_HEAVY_MODEL=qwen3-coder:480b # complex multi-step coding
193
- NEX_STANDARD_MODEL=devstral-2:123b # routine tasks
194
- NEX_FAST_MODEL=devstral-small-2:24b # quick lookups, fast sub-agents
96
+ DEFAULT_MODEL=devstral-2:123b
97
+ NEX_HEAVY_MODEL=qwen3-coder:480b
98
+ NEX_STANDARD_MODEL=devstral-2:123b
99
+ NEX_FAST_MODEL=devstral-small-2:24b
195
100
  ```
196
101
 
197
- ### Run the benchmark yourself
198
-
199
- ```bash
200
- /benchmark # full run: 62 tasks × 5 models
201
- /benchmark --quick # fast run: 14 tasks × 3 models (doubled from 7 for better resolution)
202
- /benchmark --discover # detect new Ollama Cloud models, benchmark + auto-update README
203
- /benchmark --models=minimax-m2.7:cloud,qwen3-coder:480b
204
- /benchmark --history # show OpenClaw nightly trend
205
- ```
206
-
207
- Switch anytime: `/model devstral-2:123b` or update `DEFAULT_MODEL` in `.env`.
208
- The best models discovered are automatically saved to `~/.nex-code/.env` to persist globally across all your projects.
209
- Auto-discovery runs weekly via the scheduled improvement task and updates this table automatically.
210
-
211
102
  ---
212
103
 
213
104
  ## Setup
214
105
 
215
- ### Prerequisites
216
-
217
- - Node.js 18+
218
- - At least one API key **or** a local [Ollama](https://ollama.com/download) server
219
-
220
- ### Install from npm
106
+ **Prerequisites:** Node.js 18+ and at least one API key (or local Ollama).
221
107
 
222
108
  ```bash
223
- npm install -g nex-code
224
- ```
225
-
226
- Or run directly without installing:
109
+ # .env (or set environment variables)
110
+ OLLAMA_API_KEY=your-key # Ollama Cloud
111
+ OPENAI_API_KEY=your-key # OpenAI
112
+ ANTHROPIC_API_KEY=your-key # Anthropic
113
+ GEMINI_API_KEY=your-key # Gemini
114
+ PERPLEXITY_API_KEY=your-key # optional — grounded web search
227
115
 
228
- ```bash
229
- npx nex-code
116
+ DEFAULT_PROVIDER=ollama
117
+ DEFAULT_MODEL=devstral-2:123b
230
118
  ```
231
119
 
232
- ### Install from source (for contributors)
120
+ **Install from source:**
233
121
 
234
122
  ```bash
235
123
  git clone https://github.com/hybridpicker/nex-code.git
236
- cd nex-code
237
- npm install
238
- npm run build # Build the high-performance bundle
239
- cp .env.example .env
240
- npm link
241
- npm run install-hooks
124
+ cd nex-code && npm install && npm run build
125
+ cp .env.example .env && npm link && npm run install-hooks
242
126
  ```
243
127
 
244
- ### Configure a Provider
245
-
246
- Create a `.env` file in your project directory (or set environment variables):
247
-
248
- ```bash
249
- # Pick any — only one is required
250
- OLLAMA_API_KEY=your-key # Ollama Cloud (Qwen3 Coder, Qwen3.5, DeepSeek R1, Devstral, Kimi K2.5, Llama 4, MiniMax M2.5, GLM 4.7)
251
- OPENAI_API_KEY=your-key # OpenAI (GPT-4o, GPT-4.1, o1, o3, o4-mini)
252
- ANTHROPIC_API_KEY=your-key # Anthropic (Claude Sonnet 4.6, Opus 4.6, Haiku 4.5)
253
- GEMINI_API_KEY=your-key # Google Gemini (3.1 Pro Preview, 2.5 Pro/Flash, 2.0 Flash)
254
- PERPLEXITY_API_KEY=your-key # Perplexity (optional — enables grounded web search)
255
- # No key needed for local Ollama — just have it running
256
-
257
- # Optional tuning
258
- DEFAULT_PROVIDER=ollama # Active provider on startup
259
- DEFAULT_MODEL=devstral-2:123b # Active model on startup (see /benchmark for ranking)
260
- FALLBACK_CHAIN=anthropic,openai # Providers tried on failure (comma-separated)
261
- NEX_STALE_WARN_MS=60000 # Warn if no tokens received for N ms (default: 60000)
262
- NEX_STALE_ABORT_MS=120000 # Abort and retry stream after N ms of silence (default: 120000)
263
- NEX_LANGUAGE=auto # Response language: "auto" (mirrors user's language, default) or e.g. "English", "Deutsch"
264
- NEX_THEME=dark # Force dark/light theme (overrides auto-detection). Use if colours look wrong for your terminal profile.
265
- FOOTER_DEBUG=1 # Write terminal layout debug log to /tmp/footer-debug.log
266
- ```
267
-
268
- ### Verify
269
-
270
- ```bash
271
- cd ~/any-project
272
- nex-code
273
- ```
274
-
275
- You should see the banner, your project context, and the `>` prompt.
276
-
277
128
  ---
278
129
 
279
130
  ## Usage
@@ -282,1250 +133,211 @@ You should see the banner, your project context, and the `>` prompt.
282
133
  > explain the main function in index.js
283
134
  > add input validation to the createUser handler
284
135
  > run the tests and fix any failures
285
- > refactor this to use async/await instead of callbacks
286
- ```
287
-
288
- ### Try These Scenarios
289
-
290
- **Understand an unfamiliar codebase:**
291
-
292
- ```
293
- > give me an overview of this project — architecture, key files, tech stack
294
- > how does authentication work here? trace the flow from login to session
295
- > find all API endpoints and list them with their HTTP methods
296
- ```
297
-
298
- **Fix bugs with context:**
299
-
300
- ```
301
136
  > the /users endpoint returns 500 — find the bug and fix it
302
- > tests are failing in auth.test.js — figure out why and fix it
303
- > there's a memory leak somewhere — profile the app and find it
304
- ```
305
-
306
- **Add features end-to-end:**
307
-
308
- ```
309
- > add rate limiting to all API routes (100 req/min per IP)
310
- > add a /health endpoint that checks DB connectivity
311
- > implement pagination for the GET /products endpoint
312
137
  ```
313
138
 
314
- **Refactor and improve:**
315
-
316
- ```
317
- > refactor the database queries to use a connection pool
318
- > this function is 200 lines — break it into smaller functions
319
- > migrate these callbacks to async/await
320
- ```
321
-
322
- **DevOps and CI:**
323
-
324
- ```
325
- > write a Dockerfile for this project
326
- > set up GitHub Actions CI that runs tests on push
327
- > add a pre-commit hook that runs linting
328
- ```
329
-
330
- **Multi-step autonomous work (YOLO mode):**
139
+ **YOLO mode** — skip all confirmations, auto-runs `caffeinate` on macOS:
331
140
 
332
141
  ```bash
333
142
  nex-code -yolo
334
143
  ```
335
144
 
336
- ```
337
- > read the entire src/ directory, run the tests, fix all failures, then commit
338
- > add input validation to every POST endpoint, add tests, run them
339
- > upgrade all dependencies to latest, fix any breaking changes, run tests
340
- ```
341
-
342
- The agent decides autonomously whether to use tools or just respond with text. Simple questions get direct answers. Coding tasks trigger the agentic tool loop.
343
-
344
- **Vision / Screenshot → Code** — drop an image path anywhere in your message and nex-code will send it to a vision-capable model automatically:
345
-
346
- ```
347
- > /path/to/screenshot.png implement this UI in React
348
- > describe the layout in mockup.png and generate the CSS
349
- ```
350
-
351
- Supported formats: PNG, JPG, GIF, WebP, BMP. Works with Anthropic, OpenAI, Gemini, and Ollama vision models (llava, qwen2-vl, etc.).
352
-
353
- ### YOLO Mode
354
-
355
- Skip all confirmation prompts — file changes, dangerous commands, and tool permissions are auto-approved. The banner shows a `⚡ YOLO` indicator. Toggle at runtime with `/autoconfirm`.
356
-
357
- On macOS, nex-code automatically runs `caffeinate` for the duration of the session (idle sleep and disk sleep are suppressed), so long autonomous tasks won't be interrupted by the system going to sleep. This applies to all modes, not just YOLO.
358
-
359
- You can also enable YOLO mode permanently for a project via `.nex/config.json`:
360
-
361
- ```json
362
- { "yolo": true }
363
- ```
364
-
365
- ### Headless / Programmatic Mode
366
-
367
- Run nex-code non-interactively from scripts, CI pipelines, or other processes:
145
+ **Headless / Programmatic:**
368
146
 
369
147
  ```bash
370
- # Inline prompt
371
- nex-code --task "refactor src/index.js to use async/await" --yolo
372
-
373
- # Prompt from file (avoids shell-escaping issues with special characters)
374
- nex-code --prompt-file /tmp/task.txt --yolo
375
-
376
- # Delete the file after reading
377
- nex-code --prompt-file /tmp/task.txt --delete-prompt-file --yolo
378
-
379
- # JSON output for programmatic parsing
148
+ nex-code --task "refactor src/index.js to async/await" --yolo
380
149
  nex-code --prompt-file /tmp/task.txt --yolo --json
381
- # → {"success":true,"response":"..."}
150
+ nex-code --daemon # background watcher (reads .nex/daemon.json)
382
151
  ```
383
152
 
384
- | Flag | Description |
385
- | -------------------------- | ------------------------------------------------------------------------------------------------------------- |
386
- | `--task <prompt>` | Run a single prompt and exit |
387
- | `--prompt-file <path>` | Read prompt from a UTF-8 file and run headless |
388
- | `--delete-prompt-file` | Delete the prompt file after reading (use with `--prompt-file`) |
389
- | `--auto` | Skip confirmations (non-interactive, no REPL banner) |
390
- | `--yolo` | Skip all confirmations including dangerous commands (also configurable via `.nex/config.json` `"yolo": true`) |
391
- | `--server` | Start JSON-lines IPC server (used by the VS Code extension) |
392
- | `--json` | Output `{"success":true,"response":"..."}` to stdout |
393
- | `--max-turns <n>` | Override the agentic loop iteration limit |
394
- | `--model <spec>` | Use a specific model (e.g. `anthropic:claude-sonnet-4-6`) |
395
- | `--debug` | Show internal diagnostic messages (compression, loop detection, guards) |
396
- | `--no-auto-orchestrate` | Disable auto-orchestration for multi-goal prompts (on by default; also: `NEX_AUTO_ORCHESTRATE=false`) |
397
- | `--orchestrator-model <m>` | Model for decomposition/synthesis step (default: `kimi-k2.5`) |
398
-
399
- ---
400
-
401
- ## VS Code Extension
402
-
403
- nex-code ships with a built-in VS Code extension (`vscode/`) — no separate repo needed. It adds a sidebar chat panel with streaming output, collapsible tool cards, and confirmation dialogs, all styled with VS Code's native theme variables.
404
-
405
- **Architecture:** The extension spawns `nex-code --server` as a child process and communicates over a JSON-lines protocol on stdin/stdout. No agent logic is duplicated — the CLI is the single source of truth.
153
+ | Flag | Description |
154
+ |---|---|
155
+ | `--task <prompt>` | Run a single prompt and exit |
156
+ | `--prompt-file <path>` | Read prompt from file |
157
+ | `--yolo` | Skip all confirmations |
158
+ | `--server` | JSON-lines IPC server (VS Code extension) |
159
+ | `--daemon` | Background watcher (file changes, git commits, cron) |
160
+ | `--flatrate` | 100 turns, 6 parallel agents, 5 retries |
161
+ | `--json` | JSON output to stdout |
162
+ | `--max-turns <n>` | Override agentic loop limit |
163
+ | `--model <spec>` | e.g. `anthropic:claude-sonnet-4-6` |
164
+ | `--debug` | Show diagnostic messages |
406
165
 
407
- **Requirements:** nex-code must be in `$PATH` — either `npm install -g nex-code` or `npm link` for local development.
166
+ **Vision / Screenshot:**
408
167
 
409
- **Install:**
410
-
411
- ```bash
412
- cd vscode
413
- npm install
414
- npm run package # syncs version, builds, and creates .vsix
415
- # Cmd+Shift+P → Extensions: Install from VSIX...
168
+ ```
169
+ > /path/to/screenshot.png implement this UI in React
170
+ > analyze https://example.com/mockup.png and implement it
171
+ > what's wrong with the layout in my clipboard # macOS clipboard
172
+ > screenshot localhost:3000 and review the navbar spacing
416
173
  ```
417
174
 
418
- **Settings** (`Settings → Extensions → Nex Code`):
419
-
420
- | Setting | Default | Description |
421
- | ------------------------- | ----------------- | --------------------------- |
422
- | `nexCode.executablePath` | `nex-code` | Path to the nex-code binary |
423
- | `nexCode.defaultProvider` | `ollama` | LLM provider |
424
- | `nexCode.defaultModel` | `devstral-2:123b` | Model name |
425
- | `nexCode.anthropicApiKey` | — | Anthropic API key |
426
- | `nexCode.openaiApiKey` | — | OpenAI API key |
427
- | `nexCode.ollamaApiKey` | — | Ollama Cloud API key |
428
- | `nexCode.geminiApiKey` | — | Google Gemini API key |
429
- | `nexCode.maxTurns` | `50` | Max agentic loop iterations |
430
-
431
- **Commands** (`Cmd+Shift+P`):
432
-
433
- | Command | Description |
434
- | ------------------------- | ----------------------------------------------------- |
435
- | `Nex Code: Clear Chat` | Clear conversation history |
436
- | `Nex Code: Switch Model` | Pick a different model |
437
- | `Nex Code: Restart Agent` | Restart the child process (e.g. after source changes) |
175
+ Formats: PNG, JPG, GIF, WebP, BMP. Works with all providers that support vision.
438
176
 
439
177
  ---
440
178
 
441
179
  ## Providers & Models
442
180
 
443
- Switch providers and models at runtime:
444
-
445
- ```
446
- /model # interactive model picker (arrow keys + Enter)
447
- /model openai:gpt-4o # switch directly
448
- /model anthropic:claude-sonnet
449
- /model gemini:gemini-2.5-pro
450
- /model local:llama3
451
- /providers # see all available providers & models
452
- ```
453
-
454
- | Provider | Models | Env Variable |
455
- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
456
- | **ollama** | Qwen3 Coder, Qwen3.5 (397B, 122B-A10B, 35B-A3B, 27B, 9B, 4B, 2B, 0.8B), DeepSeek R1, Devstral, Kimi K2.5, MiniMax M2.5, GLM 4.7, Llama 4 | `OLLAMA_API_KEY` |
457
- | **openai** | GPT-4o, GPT-4.1, o1, o3, o4-mini | `OPENAI_API_KEY` |
458
- | **anthropic** | Claude Sonnet 4.6, Opus 4.6, Haiku 4.5, Sonnet 4.5, Sonnet 4 | `ANTHROPIC_API_KEY` |
459
- | **gemini** | Gemini 3.1 Pro Preview, 2.5 Pro/Flash, 1.5 Pro/Flash | `GEMINI_API_KEY` |
460
- | **local** | Any model on your local Ollama server | (none) |
461
-
462
- Fallback chains let you auto-switch when a provider fails:
463
-
464
181
  ```
465
- /fallback anthropic,openai,local
182
+ /model # interactive picker
183
+ /model openai:gpt-4o # switch directly
184
+ /providers # list all
185
+ /fallback anthropic,openai # auto-switch on failure
466
186
  ```
467
187
 
468
- **Wire Protocol Layer:** All 5 providers share 3 wire protocol implementations (OpenAI-compatible SSE, Anthropic Messages SSE, Ollama NDJSON). Stream parsing, tool call accumulation, and response normalization are handled by reusable `StreamParser` classes — eliminating duplicated protocol code across providers.
188
+ | Provider | Models | Env Variable |
189
+ |---|---|---|
190
+ | **ollama** | Qwen3, DeepSeek R1, Devstral, Kimi K2, MiniMax, GLM, Llama 4 | `OLLAMA_API_KEY` |
191
+ | **openai** | GPT-4o, GPT-4.1, o1, o3, o4-mini | `OPENAI_API_KEY` |
192
+ | **anthropic** | Claude Opus 4.6, Sonnet 4.6, Haiku 4.5 | `ANTHROPIC_API_KEY` |
193
+ | **gemini** | Gemini 3.1 Pro, 2.5 Pro/Flash | `GEMINI_API_KEY` |
194
+ | **local** | Any local Ollama model | (none) |
469
195
 
470
196
  ---
471
197
 
472
198
  ## Commands
473
199
 
474
- Type `/` to see inline suggestions as you type. Tab completion is supported for slash commands and file paths (type a path containing `/` and press Tab).
475
-
476
- | Command | Description |
477
- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
478
- | `/help` | Full help |
479
- | `/model [spec]` | Show/switch model (e.g. `openai:gpt-4o`) |
480
- | `/providers` | List all providers and models |
481
- | `/fallback [chain]` | Show/set fallback chain |
482
- | `/tokens` | Token usage and context budget |
483
- | `/costs` | Session token costs |
484
- | `/budget` | Show/set per-provider cost limits |
485
- | `/clear` | Clear conversation |
486
- | `/context` | Show project context |
487
- | `/autoconfirm` | Toggle auto-confirm for file changes |
488
- | `/save [name]` | Save current session |
489
- | `/load <name>` | Load a saved session |
490
- | `/sessions` | List saved sessions |
491
- | `/resume` | Resume last session |
492
- | `/branches` | Show session tree (all conversation branches) |
493
- | `/timeline [n]` | Show message timeline of current branch |
494
- | `/goto <index>` | Jump to a message index (truncates later messages) |
495
- | `/fork [index] [name]` | Create a new branch at the given message index |
496
- | `/switch-branch <name>` | Switch to a different conversation branch |
497
- | `/delete-branch <name>` | Delete a conversation branch |
498
- | `/remember <text>` | Save a memory (persists across sessions) |
499
- | `/forget <key>` | Delete a memory |
500
- | `/memory` | Show all memories |
501
- | `/brain add <name>` | Add a document to the knowledge base |
502
- | `/brain list` | List all brain documents |
503
- | `/brain search <query>` | Search the knowledge base |
504
- | `/brain show <name>` | Show a brain document |
505
- | `/brain remove <name>` | Remove a brain document |
506
- | `/brain rebuild` | Rebuild keyword index |
507
- | `/brain embed` | Build/rebuild embedding index |
508
- | `/brain status` | Show brain status (docs, index, embeddings) |
509
- | `/brain review` | Review pending brain changes (git diff) |
510
- | `/brain undo` | Undo last brain write |
511
- | `/learn` | Reflect on session and auto-update memory + NEX.md |
512
- | `/permissions` | Show tool permissions |
513
- | `/allow <tool>` | Auto-allow a tool |
514
- | `/deny <tool>` | Block a tool |
515
- | `/plan [task]` | Plan mode (analyze before executing) |
516
- | `/plan edit` | Open current plan in `$EDITOR` for review/modification |
517
- | `/plans` | List saved plans |
518
- | `/auto [level]` | Set autonomy: interactive/semi-auto/autonomous |
519
- | `/commit [msg]` | Smart commit (analyze diff, suggest message) |
520
- | `/diff` | Show current diff |
521
- | `/branch [name]` | Create feature branch |
522
- | `/mcp` | MCP servers and tools |
523
- | `/hooks` | Show configured hooks |
524
- | `/skills` | List, enable, disable skills |
525
- | `/tree [depth]` | Show project file tree (default depth 3) |
526
- | `/retry [--model <id>]` | Retry the last user turn; optionally switch model first (`/retry --model kimi-k2.5`) |
527
- | `/undo` | Undo last file change |
528
- | `/redo` | Redo last undone change |
529
- | `/history` | Show file change history |
530
- | `/snapshot [name]` | Create a named git snapshot of current changes |
531
- | `/restore [name\|last]` | Restore a previously created snapshot |
532
- | `/review [--strict] [file]` | Deep code review: 3-phase protocol (broad scan → grep deep-dive → report), score table, diff fix snippets. `--strict` forces ≥3 critical findings. |
533
- | `/k8s [user@host]` | Kubernetes overview: namespaces + pod health (remote via SSH optional) |
534
- | `/setup` | Interactive setup wizard — configure provider, API keys, web search |
535
- | `/benchmark [--quick\|--discover\|--history]` | Rank models on nex-code tool-calling tasks, auto-update routing |
536
- | `/install-skill <url>` | Install a skill from a git repo |
537
- | `/search-skill <query>` | Search GitHub for nex-code skills |
538
- | `/remove-skill <name>` | Remove an installed skill |
539
- | `/audit` | Show tool execution audit summary |
540
- | `/exit` | Quit |
200
+ Type `/` for inline suggestions. Tab completion for commands and file paths.
201
+
202
+ | Command | Description |
203
+ |---|---|
204
+ | `/help` | Full help |
205
+ | `/model [spec]` / `/providers` | Switch model / list all |
206
+ | `/clear` | Clear conversation |
207
+ | `/save` / `/load` / `/sessions` / `/resume` | Session management |
208
+ | `/branches` / `/fork` / `/switch-branch` / `/goto` | Session tree navigation |
209
+ | `/remember` / `/forget` / `/memory` | Persistent memory |
210
+ | `/brain add\|list\|search\|show\|remove` | Knowledge base |
211
+ | `/plan [task]` / `/plan edit` / `/plan approve` | Plan mode |
212
+ | `/commit [msg]` / `/diff` / `/branch` | Git intelligence |
213
+ | `/undo` / `/redo` / `/history` | Persistent undo/redo |
214
+ | `/snapshot [name]` / `/restore` | Git snapshots |
215
+ | `/permissions` / `/allow` / `/deny` | Tool permissions |
216
+ | `/costs` / `/budget` | Cost tracking and limits |
217
+ | `/review [--strict]` | Deep code review |
218
+ | `/benchmark` | Model ranking (62 tasks) |
219
+ | `/autoresearch` / `/ar-self-improve` | Autonomous optimization loops |
220
+ | `/servers` / `/docker` / `/deploy` / `/k8s` | Infrastructure management |
221
+ | `/skills` / `/install-skill` / `/mcp` / `/hooks` | Extensibility |
222
+ | `/tree [depth]` | Project file tree |
223
+ | `/audit` | Tool execution audit |
224
+ | `/setup` | Interactive setup wizard |
541
225
 
542
226
  ---
543
227
 
544
228
  ## Tools
545
229
 
546
- The agent has 45 built-in tools:
547
-
548
- ### Core & File System
549
-
550
- | Tool | Description |
551
- | ---------------- | ------------------------------------------------------------ |
552
- | `bash` | Execute shell commands (90s timeout, 5MB buffer) |
553
- | `read_file` | Read files with optional line range (binary detection) |
554
- | `write_file` | Create or overwrite files (with diff preview + confirmation) |
555
- | `edit_file` | Targeted text replacement (with diff preview + confirmation) |
556
- | `patch_file` | Atomic multi-replacement in a single operation |
557
- | `list_directory` | Tree view with depth control and glob filtering |
558
- | `search_files` | Regex search across files (like grep) |
559
- | `glob` | Fast file search by name/extension pattern |
560
- | `grep` | Content search with regex and line numbers |
561
-
562
- ### Git & Web
563
-
564
- | Tool | Description |
565
- | ------------ | -------------------------------------------------------------------------- |
566
- | `git_status` | Git working tree status |
567
- | `git_diff` | Git diff with optional path filter |
568
- | `git_log` | Git commit history with configurable count |
569
- | `web_fetch` | Fetch content from a URL |
570
- | `web_search` | Grounded search via Perplexity (if `PERPLEXITY_API_KEY` set) or DuckDuckGo |
571
-
572
- ### Interaction & Agents
573
-
574
- | Tool | Description |
575
- | -------------- | ------------------------------------------------------ |
576
- | `ask_user` | Ask the user a question and wait for input |
577
- | `task_list` | Create and manage task lists for multi-step operations |
578
- | `spawn_agents` | Run parallel sub-agents with auto model routing |
579
- | `switch_model` | Switch active model mid-conversation |
580
-
581
- ### Browser (optional — requires Playwright)
582
-
583
- | Tool | Description |
584
- | -------------------- | ------------------------------------------------------------------ |
585
- | `browser_open` | Open URL in headless browser, return text + links (JS-heavy pages) |
586
- | `browser_screenshot` | Screenshot a URL → saved file + vision-ready path |
587
- | `browser_click` | Click element by CSS selector or visible text |
588
- | `browser_fill` | Fill form field and optionally submit |
589
-
590
- ### GitHub Actions
591
-
592
- | Tool | Description |
593
- | --------------------- | -------------------------------------------------------------------- |
594
- | `gh_run_list` | List GitHub Actions workflow runs |
595
- | `gh_run_view` | View run details and step logs |
596
- | `gh_workflow_trigger` | Trigger a workflow dispatch event |
597
- | `k8s_pods` | List Kubernetes pods (local kubectl or remote via SSH) |
598
- | `k8s_logs` | Fetch pod logs with `--tail` / `--since` filtering |
599
- | `k8s_exec` | Run a command inside a pod (with confirmation) |
600
- | `k8s_apply` | Apply a manifest file — `dry_run` mode supported (with confirmation) |
601
- | `k8s_rollout` | Rollout status / restart / history / undo for deployments |
602
-
603
- ### SSH & Server Management
604
-
605
- Requires `.nex/servers.json` — run `/init` to configure. See [Server Management](#server-management).
606
-
607
- | Tool | Description |
608
- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
609
- | `ssh_exec` | Execute a command on a remote server via SSH |
610
- | `ssh_upload` | Upload a file or directory via SCP |
611
- | `ssh_download` | Download a file or directory via SCP |
612
- | `service_manage` | Start/stop/restart/reload/enable/disable a systemd service (local or remote) |
613
- | `service_logs` | Fetch journalctl logs (local or remote, with `--since` support) |
614
- | `sysadmin` | Senior sysadmin operations on any Linux server (local or SSH). Actions: `audit` (full health overview), `disk_usage`, `process_list`, `network_status`, `package` (dnf/apt auto-detect), `user_manage` (list/create/delete/add_ssh_key), `firewall` (firewalld/ufw/iptables auto-detect), `cron` (list/add/remove), `ssl_check` (domain or cert file), `log_tail` (any log), `find_large` (big files by size). Read-only actions run without confirmation; state-changing actions require approval. |
615
- | `remote_agent` | Delegate a full coding task to a **nex-code instance running on a remote server** via SSH. Writes the task to a temp file, executes `nex-code --prompt-file ... --auto` on the remote, and streams back the result. Requires `.nex/servers.json`. Optional `project_path` (defaults to remote home dir) and `model` override. Timeout: 5 minutes. |
616
-
617
- ### Docker
618
-
619
- | Tool | Description |
620
- | ------------------ | ------------------------------------------------- |
621
- | `container_list` | List Docker containers (local or remote via SSH) |
622
- | `container_logs` | Fetch Docker container logs (`--tail`, `--since`) |
623
- | `container_exec` | Execute a command inside a running container |
624
- | `container_manage` | Start/stop/restart/remove/inspect a container |
625
-
626
- ### Deploy
627
-
628
- | Tool | Description |
629
- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
630
- | `deploy` | Deploy to a remote server via **rsync** (sync local files) or **git** (git pull on remote) + optional post-deploy script + optional health check. Supports named configs from `.nex/deploy.json`. |
631
- | `deployment_status` | Check deployment health across all configured servers — server reachability, service status, health checks. Reads `.nex/deploy.json`. |
632
-
633
- ### Frontend Design
634
-
635
- | Tool | Description |
636
- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
637
- | `frontend_recon` | **Mandatory first step before any frontend work.** Scans the project and returns: (1) design tokens — CSS custom properties (`:root`), Tailwind theme colors/fonts, (2) main layout/index page structure, (3) a reference component of the same type (`type=` hint), (4) detected JS/CSS framework stack — Vue/React, Alpine.js v2 vs v3, HTMX, Tailwind, Django. Call this before writing any markup or styles so the agent uses the project's actual design system instead of inventing one. |
638
-
639
- **Interactive commands** (vim, top, htop, ssh, tmux, fzf, etc.) are automatically detected and spawned with full TTY passthrough — no separate handling required.
640
-
641
- **Browser tools** require Playwright (`npm install playwright && npx playwright install chromium`). nex-code works without it — browser tools return a helpful install message if missing.
642
-
643
- Additional tools can be added via [MCP servers](#mcp) or [Skills](#skills).
230
+ 45 built-in tools:
644
231
 
645
- ---
232
+ **Core:** `bash`, `read_file`, `write_file`, `edit_file`, `patch_file`, `list_directory`, `search_files`, `glob`, `grep`
646
233
 
647
- ## Server Management
234
+ **Git & Web:** `git_status`, `git_diff`, `git_log`, `web_fetch`, `web_search`
648
235
 
649
- nex-code has first-class support for remote server management via SSH, optimised for **AlmaLinux 9** and **macOS**.
236
+ **Agents:** `ask_user`, `task_list`, `spawn_agents`, `switch_model`
650
237
 
651
- ### Setup
238
+ **Browser** (optional, requires Playwright): `browser_open`, `browser_screenshot`, `browser_click`, `browser_fill`
652
239
 
653
- Run `/init` inside nex-code to interactively configure your servers:
654
-
655
- ```
656
- > /init
657
- ```
240
+ **GitHub Actions & K8s:** `gh_run_list`, `gh_run_view`, `gh_workflow_trigger`, `k8s_pods`, `k8s_logs`, `k8s_exec`, `k8s_apply`, `k8s_rollout`
658
241
 
659
- Or create `.nex/servers.json` manually:
660
-
661
- ```json
662
- {
663
- "prod": {
664
- "host": "94.130.37.43",
665
- "user": "deploy",
666
- "port": 22,
667
- "key": "~/.ssh/id_rsa",
668
- "os": "almalinux9",
669
- "sudo": true
670
- },
671
- "macbook": {
672
- "host": "192.168.1.10",
673
- "user": "lukas",
674
- "os": "macos"
675
- }
676
- }
677
- ```
242
+ **SSH & Server:** `ssh_exec`, `ssh_upload`, `ssh_download`, `service_manage`, `service_logs`, `sysadmin`, `remote_agent`
678
243
 
679
- **OS values**: `almalinux9`, `almalinux8`, `ubuntu`, `debian`, `macos`
680
-
681
- When `.nex/servers.json` exists, the agent automatically receives OS-aware context:
682
-
683
- - **AlmaLinux 9**: `dnf`, `firewalld`, `systemctl`, SELinux hints
684
- - **macOS**: `brew`, `launchctl`, `log show` instead of `journalctl`
685
-
686
- If the project also has a `NEX.md` containing deployment indicators (`ssh`, `server`, `systemctl`, etc.), nex-code injects a **Deployment Context** block at the top of its system prompt. This tells the model that the application runs on the remote server — not locally — and steers debugging toward `ssh_exec`/`service_logs` instead of local `read_file` calls on server-side paths like `logs/`.
687
-
688
- ### Slash Commands
689
-
690
- | Command | Description |
691
- | -------------------------- | -------------------------------------------------- |
692
- | `/servers` | List all configured server profiles |
693
- | `/servers ping` | Check SSH connectivity for all servers in parallel |
694
- | `/servers ping <name>` | Check a specific server |
695
- | `/docker` | List running containers across all servers + local |
696
- | `/docker -a` | Include stopped containers |
697
- | `/deploy` | List all named deploy configs |
698
- | `/deploy <name>` | Run a named deploy (with confirmation) |
699
- | `/deploy <name> --dry-run` | Preview without syncing |
700
- | `/init` | Interactive wizard: create `.nex/servers.json` |
701
- | `/init deploy` | Interactive wizard: create `.nex/deploy.json` |
702
-
703
- ### Named Deploy Configs
704
-
705
- Create `.nex/deploy.json` (or use `/init deploy`):
706
-
707
- ```json
708
- {
709
- "prod": {
710
- "server": "prod",
711
- "method": "rsync",
712
- "local_path": "dist/",
713
- "remote_path": "/var/www/app",
714
- "exclude": ["node_modules", ".env"],
715
- "deploy_script": "systemctl restart gunicorn",
716
- "health_check": "https://myapp.example.com/health"
717
- },
718
- "api": {
719
- "server": "prod",
720
- "method": "git",
721
- "remote_path": "/home/deploy/my-api",
722
- "branch": "main",
723
- "deploy_script": "npm ci --omit=dev && sudo systemctl restart my-api",
724
- "health_check": "systemctl is-active my-api"
725
- }
726
- }
727
- ```
244
+ **Docker:** `container_list`, `container_logs`, `container_exec`, `container_manage`
728
245
 
729
- Then deploy with:
246
+ **Deploy:** `deploy`, `deployment_status`
730
247
 
731
- ```
732
- > /deploy prod
733
- ```
248
+ **Frontend:** `frontend_recon` — scans design tokens, layout, and framework stack before any frontend work
734
249
 
735
- Or from within a conversation:
250
+ **Visual:** `visual_diff`, `responsive_sweep`, `visual_annotate`, `visual_watch`, `design_tokens`, `design_compare`
736
251
 
737
- ```
738
- deploy the latest build to prod
739
- ```
252
+ Additional tools via [MCP servers](#mcp) or [Skills](#skills).
740
253
 
741
254
  ---
742
255
 
743
- ## Features
744
-
745
- ### Compact Output
746
-
747
- The agent loop uses a bouncing-ball spinner (`● · · · ·` → `· ● · · ·` → …) during tool execution, then prints compact 1-line summaries:
748
-
749
- ```
750
- ⏺ Read, Grep, Edit
751
- ⎿ Read 45 lines from app.js
752
- ⎿ 12 matches "TODO"
753
- ⎿ old_text not found
754
- ```
755
-
756
- After multi-step tasks, a résumé and context-aware follow-up suggestions are shown:
757
-
758
- ```
759
- ── 3 steps · 8 tools · 2 files modified · 37s ──
760
- 💡 /diff · /commit · /undo
761
- ```
762
-
763
- Step counts match between inline `── step N ──` markers and the résumé. Elapsed time is included. Read-heavy sessions (analysis, status checks) suggest `/save · /clear` instead.
764
-
765
- When the model runs tools but produces no visible text, an automatic nudge forces it to summarize findings — preventing silent completions where the user sees nothing.
766
-
767
- ### Response Quality
768
-
769
- The system prompt enforces substantive responses: the model always presents findings as formatted text after using tools (users only see 1-line tool summaries). Responses use markdown with headers, bullet lists, and code blocks. The model states its approach before non-trivial tasks and summarizes results after completing work.
770
-
771
- **Language:** By default (`NEX_LANGUAGE=auto`), the model mirrors the language of the user's message — write in German, get a German response; write in English, get an English response. Set `NEX_LANGUAGE=English` (or any language) to force a fixed response language.
772
-
773
- **Code examples:** The model is instructed to always show actual, working code — never pseudocode or placeholder snippets.
774
-
775
- ### Performance
776
-
777
- - **Asynchronous I/O**: The entire CLI is built on non-blocking I/O. File reads, writes, and git operations never block the main thread, keeping the UI responsive even during heavy tasks.
778
- - **Fast Startup**: Pre-bundled with `esbuild` to minimize module loading overhead, achieving sub-100ms startup times.
779
- - **In-Memory Indexing**: A background indexing engine (using `ripgrep` or a fast fallback) keeps project file paths in RAM for instant file discovery, path auto-fixing, and glob searches.
780
-
781
- ### Streaming Output
782
-
783
- Tokens appear live as the model generates them. Bouncing-ball spinner during connection, then real-time line-by-line rendering via `StreamRenderer` with terminal width-aware word wrapping, markdown formatting, and syntax highlighting (JS, TS, Python, Go, Rust, CSS, HTML, and more).
784
-
785
- ### Paste Detection
786
-
787
- Automatic bracketed paste mode: pasting multi-line text into the prompt is detected and combined into a single input. A `[Pasted content — N lines]` indicator is shown with a preview of the first line. The user must press Enter to send — pasted content never auto-fires. The paste handler stores the combined text and waits for explicit submission.
788
-
789
- ### Ctrl+C Cancellation
790
-
791
- Pressing Ctrl+C during a running request immediately cancels the active HTTP stream and returns to the prompt:
792
-
793
- - An `AbortController` signal flows from the readline SIGINT handler through the agent loop to the provider's HTTP request
794
- - All providers (Ollama, OpenAI, Anthropic, Gemini, local) destroy the response stream on abort
795
- - No EPIPE errors after cancellation (stdout writes are EPIPE-guarded)
796
- - During processing: first Ctrl+C aborts the task and returns to prompt; second Ctrl+C force-exits
797
- - At the idle prompt: first Ctrl+C shows `(Press Ctrl+C again to exit)`, second Ctrl+C exits (hint resets after 2 s)
798
- - readline intercepts Ctrl+C on TTY (`rl.on('SIGINT')`) to prevent readline close → `process.exit(0)` race
799
-
800
- ### Diff Preview
801
-
802
- Every file change is shown in a diff-style format before being applied:
803
-
804
- - **Header**: `⏺ Update(file)` or `⏺ Create(file)` with relative path
805
- - **Summary**: `⎿ Added N lines, removed M lines`
806
- - **Numbered lines**: right-justified line numbers with red `-` / green `+` markers
807
- - **Context**: 3 lines of surrounding context per change, multiple hunks separated by `···`
808
- - OOM-safe: large diffs (>2000 lines) fall back to add/remove instead of LCS
809
- - All changes require `[y/n]` confirmation (toggle with `/autoconfirm` or start with `-yolo`)
810
-
811
- ### Terminal Theme Detection
812
-
813
- Nex Code automatically adapts all colours to your terminal's background:
256
+ ## Key Features
814
257
 
815
- - **Dark terminals** — bright, saturated palette with `\x1b[2m` dim for muted text
816
- - **Light/white terminals** — darker, high-contrast palette; dim replaced with explicit grey to stay visible on white backgrounds; command echo uses a light blue-grey highlight instead of dark grey
817
-
818
- Detection priority:
819
-
820
- 1. `NEX_THEME=light|dark` env var — explicit override, useful if auto-detection is wrong
821
- 2. `COLORFGBG` env var — set by iTerm2 and other terminals
822
- 3. **OSC 11 query** — asks the terminal emulator directly for its background colour (works with Apple Terminal, iTerm2, WezTerm, Ghostty, and most xterm-compatible terminals). Result is cached per terminal session in `~/.nex-code/.theme_cache.json`, so the one-time ~100 ms startup cost only occurs on first launch in each terminal window.
823
- 4. Default → dark
824
-
825
- If you use multiple Apple Terminal profiles (e.g. white, dark teal, dark green), each window is detected independently — no manual configuration needed.
826
-
827
- ### Auto-Context
828
-
829
- On startup, the CLI reads your project and injects context into the system prompt:
830
-
831
- - `package.json` — name, version, scripts, dependencies
832
- - `README.md` — first 50 lines
833
- - Git info — branch, status, recent commits
834
- - `.gitignore` content
835
- - **Merge conflicts** — detected and shown as a red warning; included in LLM context so the agent avoids editing conflicted files
836
-
837
- ### Context Engine
838
-
839
- Automatic token management with compression when the context window gets full. Tracks token usage across system prompt, conversation, tool results, and tool definitions.
840
-
841
- ### Safety Layer
842
-
843
- Three tiers of protection:
844
-
845
- - **Forbidden** (blocked): `rm -rf /`, `rm -rf .`, `mkfs`, `dd if=`, fork bombs, `curl|sh`, `cat .env`, `chmod 777`, reverse shells — 30+ patterns
846
- - **Critical** (always re-prompted, even in YOLO mode): `rm -rf`, `sudo`, `--no-verify` (hook bypass), `git reset --hard`, `git clean -f`, `git checkout --`, `git push --force` — every run requires explicit confirmation, no exceptions
847
- - **Notable** (confirmation on first use): `git push`, `npm publish`, `ssh`, `HUSKY=0`, `SKIP_HUSKY=1` — first-time prompt, then respects "always allow"
848
- - **SSH read-only safe list**: Common read-only SSH commands (`systemctl status`, `journalctl`, `tail`, `cat`, `git pull`, etc.) skip the dangerous-command confirmation
849
- - **Path protection**: Sensitive paths (`.ssh/`, `.aws/`, `.env`, credentials) are blocked from file operations
850
- - **Loop detection**: Edit-loop abort after 4 edits to the same file (warn at 2); bash-command loop abort after 8 identical commands (warn at 5); consecutive-error abort after 10 failures (warn at 6)
851
- - **Stale-stream detection**: Warns after 60 s without tokens (shows retry count + seconds until auto-abort); auto-switches to the fast model on retry 1 and offers interactive recovery when all retries are exhausted
852
- - **Auto Plan Mode**: Implementation tasks (`implement`, `refactor`, `create`, `build`, `add`, `write`, …) automatically activate plan mode — read-only analysis first, approve before any writes. Disable with `NEX_AUTO_PLAN=0`
853
- - **Intent-first behavior**: Before executing, the agent understands why you asked. If it finds something that contradicts or already satisfies the task, it asks instead of proceeding blindly
854
- - **Pre-push secret detection**: Git hook scans diffs for API keys, private keys, hardcoded secrets, SSH+IP patterns, and `.env` leaks before allowing push
855
- - **Post-merge automation**: Auto-bumps patch version on `devel→main` merge; runs `npm install` when `package.json` changes
856
-
857
- ### Sessions
858
-
859
- nex-code automatically saves your conversation after every turn. If the process crashes or is closed unexpectedly, the next startup will detect the autosave and offer to restore it:
860
-
861
- ```
862
- Previous session found. Resume? (y/n)
863
- ```
864
-
865
- Only sessions from the last 24 hours are offered for auto-resume. Older autosaves are silently skipped.
866
-
867
- **Session commands:**
868
-
869
- | Command | Description |
870
- | -------------- | -------------------------------------------------------- |
871
- | `/save <name>` | Save current conversation under a named slot |
872
- | `/load <name>` | Restore a previously saved session |
873
- | `/sessions` | List all saved sessions with message count and timestamp |
874
- | `/resume` | Resume the most recently saved session |
875
-
876
- ```
877
- /save my-feature # save with name
878
- /load my-feature # restore by name
879
- /sessions # list all saved sessions
880
- /resume # restore the latest session
881
- ```
882
-
883
- Sessions are stored in `.nex/sessions/` as JSON files. Auto-saves always write to `_autosave` (overwritten each turn). Writes are atomic — a temp file is written and renamed, so a crash mid-write never corrupts the saved state.
884
-
885
- ### Session Trees
258
+ ### Multi-Agent Orchestrator
886
259
 
887
- Navigate your conversation history like git branches. Fork at any point, explore alternative approaches, and switch between branches:
260
+ Multi-goal prompts auto-decompose into parallel sub-agents (up to 5 simultaneously, with file locking):
888
261
 
889
- ```
890
- /timeline # see message indices
891
- /fork 5 experiment # branch from message 5
892
- /branches # see all branches
893
- /switch-branch main # go back to main
894
- /goto 3 # jump to message 3 (truncates later messages)
895
- /delete-branch experiment
262
+ ```bash
263
+ nex-code --task "fix type errors in src/, add JSDoc to utils/, update CHANGELOG"
896
264
  ```
897
265
 
898
- This enables non-linear conversations: try an approach, and if it doesn't work, fork from an earlier point and try something different — without losing the original attempt.
899
-
900
266
  ### Autoresearch
901
267
 
902
- Autonomous optimization loops inspired by [Karpathy's autoresearch](https://github.com/karpathy/autoresearch). The agent creates a dedicated experiment branch, edits code, runs experiments, and automatically keeps improvements or reverts failures:
268
+ Autonomous optimization loops — edit → experiment → keep/revert, on a dedicated git branch:
903
269
 
904
270
  ```
905
271
  /autoresearch reduce test runtime while maintaining correctness
906
- /autoresearch optimize bundle size under 500kb
907
- ```
908
-
909
- The agent follows a repeating cycle on a dedicated `autoresearch/<tag>` branch: **setup branch** -> **checkpoint** -> **edit** -> **run experiment** -> **log result** -> **keep or revert (git reset)**. Runs indefinitely until you interrupt. Experiments are logged to `.nex/autoresearch/experiments.json` with metrics, resource usage, and complexity tracking. Output can be redirected to log files with metric extraction via grep patterns to protect context.
910
-
911
- ```
912
- /ar-self-improve # self-improvement loop using nex-code's benchmark as metric
913
- /ar-self-improve sysadmin # focus on a specific weak category
914
- /ar-status # show experiment history with trends
915
- /ar-clear # reset experiment history
916
- ```
917
-
918
- The loop can also run **headless** — useful for unattended overnight sessions:
919
-
920
- ```bash
921
- nex-code --task "/ar-self-improve" --no-auto-orchestrate --max-turns 200
272
+ /ar-self-improve # uses nex-code's own benchmark as the fitness metric
922
273
  ```
923
274
 
924
- `/ar-self-improve` uses nex-code's own 14-task quick benchmark as the fitness metric. Each experiment that raises the average score above the session baseline is kept; all others are reverted with `git reset`. The benchmark output includes a **Failing tasks** section that names which tasks each model got wrong, making root causes immediately visible.
925
-
926
- > **Self-improvement history** (2026-03-31): baseline 86.7 → **92.9** (+6.2 pts) in one session. Key fix: rewording the `edit_file` tool description so models call it directly instead of first calling `read_file`. `rnj-1:8b` jumped from 77.1 → 97.9 on that change alone.
927
-
928
- ### Memory
929
-
930
- Persistent project memory that survives across sessions:
931
-
932
- ```
933
- /remember lang=TypeScript
934
- /remember always use yarn instead of npm
935
- /memory
936
- /forget lang
937
- ```
938
-
939
- Also loads `NEX.md` from project root for project-level instructions.
940
-
941
- ### Brain — Persistent Knowledge Base
942
-
943
- A project-scoped knowledge base stored in `.nex/brain/`. The agent automatically retrieves relevant documents for each query and can write new entries as it discovers useful patterns, decisions, or context:
944
-
945
- ```
946
- /brain add auth-flow # add a document (prompted for content)
947
- /brain search "jwt token" # keyword + semantic search
948
- /brain list # list all documents
949
- /brain show auth-flow # display a document
950
- /brain remove auth-flow # delete a document
951
- /brain status # index health (docs, keywords, embeddings)
952
- /brain review # git diff of recent brain writes
953
- /brain undo # undo last brain write
954
- ```
955
-
956
- The agent uses the `brain_write` tool to save discoveries automatically. All writes are tracked in git so you can review, revert, or audit what the agent has stored.
957
-
958
275
  ### Plan Mode
959
276
 
960
- Analyze before executing — the agent explores the codebase with read-only tools, produces a structured plan, then you approve before any changes are made.
961
-
962
- **Auto Plan Mode** — nex-code automatically activates plan mode when it detects an implementation task (prompts containing `implement`, `refactor`, `create`, `build`, `add`, `write`, etc.). No manual `/plan` needed:
277
+ Auto-activates for implementation tasks. Read-only analysis first, approve before writes. Hard-enforced tool restrictions during analysis phase.
963
278
 
964
- ```
965
- > implement a search endpoint # → Auto Plan Mode activates immediately
966
- > refactor the auth module # → Auto Plan Mode activates immediately
967
- > how does auth work? # → normal mode (question, not implementation)
968
- ```
279
+ ### Daemon / Watch Mode
969
280
 
970
- Disable with `NEX_AUTO_PLAN=0` if you prefer manual control.
281
+ Background process that fires tasks on file changes, git commits, or cron schedule. Configured via `.nex/daemon.json`. Desktop and Matrix notifications.
971
282
 
972
- ```
973
- /plan refactor the auth module # manual: enter plan mode with optional task
974
- /plan status # show extracted steps with status icons
975
- /plan edit # open plan in $EDITOR (nano/vim/code) to modify
976
- /plan approve # approve and exit plan mode (all tools re-enabled)
977
- /auto semi-auto # set autonomy level
978
- ```
979
-
980
- Plan mode is **hard-enforced**: only read-only tools (`read_file`, `list_directory`, `search_files`, `glob`, `grep`, `web_search`, `web_fetch`, `git_status`, `git_diff`, `git_log`, `git_show`, `ask_user`) are available. Any attempt to call a write tool is blocked at the API level.
981
-
982
- **Step extraction**: when the LLM outputs a numbered plan, steps are automatically parsed into a structured list. During execution the spinner shows `Plan step 2/4: Implement tests` and `/plan status` shows per-step progress (○ pending → → in progress → ✓ done). The plan text is saved to `.nex/plans/current-plan.md`.
983
-
984
- ### Snapshots
985
-
986
- Named git snapshots — save and restore working-tree state at any point:
987
-
988
- ```
989
- /snapshot before-refactor # create snapshot named "before-refactor"
990
- /snapshot list # list all saved snapshots
991
- /restore last # restore most recent snapshot
992
- /restore before-refactor # restore by name
993
- /restore list # show all available snapshots
994
- ```
995
-
996
- Snapshots use `git stash` internally — no extra state files. The working tree is restored immediately after stashing so your changes are preserved. Use `/restore` when you want to roll back to a known-good state.
997
-
998
- ### File Tree
999
-
1000
- Visualize the project structure:
1001
-
1002
- ```
1003
- /tree # show tree at depth 3
1004
- /tree 2 # shallower view
1005
- /tree 5 # deeper view (max 8)
1006
- ```
1007
-
1008
- Automatically excludes `node_modules`, `.git`, `dist`, `build`, `coverage`, and all entries listed in `.gitignore`. Directories are sorted before files.
1009
-
1010
- ### Undo / Redo (Persistent)
1011
-
1012
- Undo/redo for all file changes (write, edit, patch) — **survives restart**:
1013
-
1014
- ```
1015
- /undo # undo last file change
1016
- /redo # redo last undone change
1017
- /history # show file change history
1018
- ```
1019
-
1020
- Undo stack holds up to 50 changes, persisted to `.nex/history/`. Large files (>100KB) are deduplicated via SHA-256 blob storage. History is auto-pruned after 7 days. `/clear` resets the in-memory stack.
1021
-
1022
- > **Snapshots vs Undo**: `/undo` operates on the persistent change stack for fine-grained per-file rollback across sessions. `/snapshot` + `/restore` use git stash for broader checkpoints across multiple files.
1023
-
1024
- ### Desktop Notifications
1025
-
1026
- On macOS, nex-code fires a system notification when a task completes after ≥ 30 seconds — useful when running long autonomous tasks in the background. No configuration needed; requires macOS Notification Center access.
1027
-
1028
- ### Task Management
1029
-
1030
- Create structured task lists for complex multi-step operations:
1031
-
1032
- ```
1033
- /tasks # show current task list
1034
- /tasks clear # clear all tasks
1035
- ```
1036
-
1037
- The agent uses `task_list` to create, update, and track progress on tasks with dependency support.
1038
-
1039
- When the agent creates a task list, a **live animated display** replaces the static output:
1040
-
1041
- ```
1042
- ✽ Adding cost limit functions… (1m 35s · ↓ 2.6k tokens)
1043
- ⎿ ✔ Create cli/picker.js — Interactive Terminal Picker
1044
- ◼ Add cost limits to cli/costs.js
1045
- ◻ Add budget gate to cli/providers/registry.js
1046
- ◻ Update cli/index.js
1047
- ◻ Run tests
1048
- ```
1049
-
1050
- - Bouncing-ball spinner (⏺ ping-pong across 5 positions) with elapsed time display
1051
- - Per-task status icons: `✔` done, `◼` in progress, `◻` pending, `✗` failed
1052
- - Automatically pauses during text streaming and resumes during tool execution
1053
- - Falls back to the static `/tasks` view when no live display is active
1054
-
1055
- ### Sub-Agents
1056
-
1057
- Spawn parallel sub-agents for independent tasks:
1058
-
1059
- - Up to 5 agents run simultaneously with their own conversation contexts
1060
- - File locking prevents concurrent writes to the same file (intra-process sub-agents)
1061
- - Multi-progress display shows real-time status of each agent
1062
- - Good for: reading multiple files, analyzing separate modules, independent research
1063
-
1064
- ### Multi-Agent Orchestrator
1065
-
1066
- For complex tasks with multiple independent goals (e.g. "fix all TypeScript errors in auth/, add tests for utils/, and update the README"), the orchestrator decomposes the prompt into parallel sub-tasks, runs dedicated sub-agents on each, and synthesizes the results.
1067
-
1068
- **Auto-orchestration is on by default** for prompts with ≥3 goals.
1069
-
1070
- ```bash
1071
- # Just use it — multi-goal prompts auto-decompose into parallel agents
1072
- nex-code --task "fix all type errors in src/, add JSDoc to utils/, update CHANGELOG"
1073
-
1074
- # Custom orchestrator model
1075
- nex-code --orchestrator-model kimi-k2.5 --task "..."
1076
-
1077
- # Disable auto-orchestration
1078
- NEX_AUTO_ORCHESTRATE=false nex-code
1079
-
1080
- # Lower the goal threshold (default: 3)
1081
- NEX_ORCHESTRATE_THRESHOLD=2 nex-code
1082
- ```
1083
-
1084
- **Interactive:** type `/orchestrate <task>` at the prompt.
1085
-
1086
- **Example output:**
1087
-
1088
- ```
1089
- Orchestrator model: kimi-k2.5 | workers: devstral-2:123b | max parallel: 3
1090
-
1091
- Phase 1: Decomposing prompt into sub-tasks...
1092
- Decomposed into 3 sub-tasks:
1093
- t1: Fix TypeScript errors in src/auth/
1094
- scope: src/auth/
1095
- t2: Add JSDoc comments to src/utils/
1096
- scope: src/utils/
1097
- t3: Update CHANGELOG with recent changes
1098
- scope: CHANGELOG.md
1099
-
1100
- Phase 2: Running 3 sub-agents (max 3 parallel)...
1101
-
1102
- ✓ Agent 1 [devstral-2:123b]: Fix TypeScript errors in src/auth/: fixed 4 type errors in login.ts, ...
1103
- ✓ Agent 2 [devstral-2:123b]: Add JSDoc comments to src/utils/: documented 12 functions across 3 files
1104
- ✓ Agent 3 [devstral-2:123b]: Update CHANGELOG: added entries for v1.2.0 changes
1105
-
1106
- Phase 3: Synthesizing results...
1107
-
1108
- Summary: Fixed 4 TS errors in auth module, added JSDoc to 12 utility functions, updated CHANGELOG.
1109
- Suggested commit: fix: resolve auth type errors and add utility docs
1110
- ```
1111
-
1112
- **Env vars:**
1113
-
1114
- | Variable | Default | Description |
1115
- | --------------------------- | ------- | ------------------------------------------------------- |
1116
- | `NEX_AUTO_ORCHESTRATE` | `true` | Set to `false` to disable auto-orchestration |
1117
- | `NEX_ORCHESTRATE_THRESHOLD` | `3` | Minimum number of detected goals before auto-triggering |
1118
-
1119
- **Model roles in orchestration:**
1120
-
1121
- | Role | Default model | Purpose |
1122
- | ------------ | ----------------- | ------------------------------------------- |
1123
- | Orchestrator | `kimi-k2.5` | Decomposes prompt, synthesizes results |
1124
- | Worker | `devstral-2:123b` | Executes each sub-task (one agent per task) |
1125
-
1126
- Override via `--orchestrator-model` (orchestrator) or `DEFAULT_MODEL` / `NEX_STANDARD_MODEL` (workers).
1127
-
1128
- ---
1129
-
1130
- ### Parallel Sessions
1131
-
1132
- Running multiple nex-code instances in the same project directory is safe. All shared state files (`.nex/memory/memory.json`, `.nex/config.json`, `NEX.md`, brain index) use advisory inter-process locking (`O_EXCL` lock files with stale-lock reclaim) and atomic writes (temp file + `rename`). A session in Terminal A and a session in Terminal B can both call `/remember`, `/allow`, or `/learn` simultaneously without data corruption.
1133
-
1134
- **Multi-Model Routing** — Sub-agents auto-select the best model per task based on complexity:
1135
-
1136
- - **Read/search/list** tasks → fast models (essential tier)
1137
- - **Edit/fix/analyze** tasks → capable models (standard tier)
1138
- - **Refactor/implement/generate** tasks → most powerful models (full tier)
1139
-
1140
- The LLM can also explicitly override with `model: "provider:model"` in the agent definition. When multiple providers are configured, the system prompt includes a routing table showing all available models and their tiers.
1141
-
1142
- ### Git Intelligence
1143
-
1144
- ```
1145
- /commit # analyze diff, suggest commit message
1146
- /commit feat: add login
1147
- /diff # show current diff summary
1148
- /branch my-feature # create and switch to branch
1149
- ```
1150
-
1151
- ### Permissions
1152
-
1153
- Control which tools the agent can use:
1154
-
1155
- ```
1156
- /permissions # show current settings
1157
- /allow read_file # auto-allow without asking
1158
- /deny bash # block completely
1159
- ```
1160
-
1161
- Persisted in `.nex/config.json`.
1162
-
1163
- ### Cost Tracking
1164
-
1165
- Track token usage and costs per provider:
1166
-
1167
- ```
1168
- /costs
1169
- /costs reset
1170
- ```
283
+ ### Session Trees
1171
284
 
1172
- ### Cost Limits
285
+ Navigate conversation history like git branches — fork, switch, goto, delete branches without losing prior attempts.
1173
286
 
1174
- Set per-provider spending limits. When a provider exceeds its budget, calls automatically fall back to the next provider in the fallback chain:
287
+ ### Safety
1175
288
 
1176
- ```
1177
- /budget # show all limits + current spend
1178
- /budget anthropic 5 # set $5 limit for Anthropic
1179
- /budget openai 10 # set $10 limit for OpenAI
1180
- /budget anthropic off # remove limit
1181
- ```
289
+ | Layer | What it guards | Bypass? |
290
+ |---|---|---|
291
+ | **Forbidden patterns** | `rm -rf /`, fork bombs, reverse shells, `cat .env` | No |
292
+ | **Protected paths** | Destructive ops on `.env`, `.ssh/`, `.aws/`, `.git/` | `NEX_UNPROTECT=1` |
293
+ | **Sensitive file tools** | read/write/edit on `.env`, `.ssh/`, `.npmrc`, `.kube/` | No |
294
+ | **Critical commands** | `rm -rf`, `sudo`, `git push --force`, `git reset --hard` | Explicit confirmation |
1182
295
 
1183
- Limits are persisted in `.nex/config.json`. You can also set them directly:
296
+ Pre-push secret detection, audit logging (JSONL), persistent undo/redo, cost limits, auto plan mode.
1184
297
 
1185
- ```json
1186
- // .nex/config.json
1187
- {
1188
- "costLimits": {
1189
- "anthropic": 5,
1190
- "openai": 10
1191
- }
1192
- }
1193
- ```
298
+ **Reporting vulnerabilities:** Email **security@schoensgibl.com** — not a public issue. 72h initial response.
1194
299
 
1195
300
  ### Open-Source Model Robustness
1196
301
 
1197
- Four features that make Nex Code significantly more reliable with open-source models:
1198
-
1199
- **Tool Call Retry with Schema Hints** — When a model sends malformed tool arguments, instead of a bare error, the agent sends back the expected JSON schema so the model can self-correct on the next loop iteration.
1200
-
1201
- **Smart Argument Parsing** — 5 fallback strategies for parsing tool arguments: direct JSON, trailing comma/quote fixes, JSON extraction from surrounding text, unquoted key repair, and markdown code fence stripping (common with DeepSeek R1, Llama).
1202
-
1203
- **Tool Argument Validation** — Validates arguments against tool schemas before execution. Auto-corrects similar parameter names (Levenshtein distance), fixes type mismatches (string↔number↔boolean), and provides "did you mean?" suggestions.
1204
-
1205
- **Auto-Fix Engine** — Three layers of automatic error recovery that silently fix common tool failures:
1206
-
1207
- - **Path auto-fix**: Wrong extension? Finds the right one (`.js` → `.ts`). File moved? Globs for it by basename. Double slashes, missing extensions — all auto-resolved.
1208
- - **Edit auto-fix**: Close match (≤5% Levenshtein distance) in `edit_file`/`patch_file` is auto-applied instead of erroring. Stacks with fuzzy whitespace matching.
1209
- - **Bash error hints**: Enriches error output with actionable hints — "command not found" → install suggestion, `MODULE_NOT_FOUND` → `npm install <pkg>`, port in use, syntax errors, TypeScript errors, test failures, and more.
1210
-
1211
- **Stale Stream Recovery** — Progressive retry strategy when streams stall (common with large Ollama models after many agent steps):
1212
-
1213
- - 1st retry: 3s backoff delay, resend same context (handles transient stalls)
1214
- - 2nd retry: force-compress conversation (~80k tokens freed), 5s delay, retry with smaller context
1215
- - Last resort: if retries exhausted, one final force-compress + reset for fresh attempts
1216
- - Broader context-too-long detection catches Ollama-specific error formats (`num_ctx`, `prompt`, `size`, `exceeds`)
1217
-
1218
- **Tool Tiers** — Dynamically reduces the tool set based on model capability:
302
+ - **5-layer argument parsing** — JSON, trailing fix, extraction, key repair, fence stripping
303
+ - **Tool call retry with schema hints** — malformed args get the expected schema for self-correction
304
+ - **Auto-fix engine** — path resolution, edit fuzzy matching (Levenshtein), bash error hints
305
+ - **Tool tiers** — essential (5) / standard (21) / full (45), auto-selected per model capability
306
+ - **Stale stream recovery** — progressive retry with context compression on stall
1219
307
 
1220
- - **essential** (5 tools): bash, read_file, write_file, edit_file, list_directory
1221
- - **standard** (21 tools): + search_files, glob, grep, ask_user, git_status, git_diff, git_log, task_list, ssh_exec, service_manage, service_logs, container_list, container_logs, container_exec, container_manage, deploy
1222
- - **full** (45 tools): all tools
308
+ ### Visual Development Tools
1223
309
 
1224
- Models are auto-classified, or override per-model in `.nex/config.json`:
1225
-
1226
- ```json
1227
- {
1228
- "toolTiers": {
1229
- "deepseek-r1": "essential",
1230
- "local:*": "essential",
1231
- "qwen3-coder": "full"
1232
- },
1233
- "maxIterations": 100
1234
- }
1235
- ```
1236
-
1237
- `maxIterations` sets the agentic loop limit project-wide (default: 50). The `--max-turns <n>` CLI flag overrides it per run.
1238
-
1239
- Tiers are also used by sub-agent routing — when a sub-agent auto-selects a model, its tool set is filtered to match that model's tier.
310
+ Pixel-level before/after diffs, responsive sweeps (320–1920px), annotation overlays, design token extraction, and live-reload diff watching. Pure image tools work standalone; browser tools need Playwright.
1240
311
 
1241
312
  ---
1242
313
 
1243
- ## Skills
314
+ ## Extensibility
1244
315
 
1245
- Extend Nex Code with project-specific knowledge, commands, and tools via `.nex/skills/`.
316
+ ### Skills
1246
317
 
1247
- ### Prompt Skills (`.md`)
318
+ Drop `.md` or `.js` files in `.nex/skills/` for project-specific knowledge, commands, and tools. Global skills in `~/.nex-code/skills/`. Install from git: `/install-skill user/repo`.
1248
319
 
1249
- Drop a Markdown file and its content is injected into the system prompt:
320
+ ### Plugins
1250
321
 
1251
- ```markdown
1252
- <!-- .nex/skills/code-style.md -->
1253
-
1254
- # Code Style
1255
-
1256
- - Always use semicolons
1257
- - Prefer const over let
1258
- - Use TypeScript strict mode
1259
- ```
1260
-
1261
- ### Script Skills (`.js`)
1262
-
1263
- CommonJS modules that can provide instructions, slash commands, and tools:
1264
-
1265
- ```javascript
1266
- // .nex/skills/deploy.js
1267
- module.exports = {
1268
- name: "deploy",
1269
- description: "Deployment helper",
1270
- instructions: "When deploying, always run tests first...",
1271
- commands: [
1272
- {
1273
- cmd: "/deploy",
1274
- desc: "Run deployment",
1275
- handler: (args) => {
1276
- /* ... */
1277
- },
1278
- },
1279
- ],
1280
- tools: [
1281
- {
1282
- type: "function",
1283
- function: {
1284
- name: "deploy_status",
1285
- description: "Check status",
1286
- parameters: { type: "object", properties: {} },
1287
- },
1288
- execute: async (args) => "deployed",
1289
- },
1290
- ],
1291
- };
1292
- ```
1293
-
1294
- ### Management
1295
-
1296
- ```
1297
- /skills # list loaded skills
1298
- /skills enable code-style # enable a skill
1299
- /skills disable code-style # disable a skill
1300
- ```
322
+ Custom tools and lifecycle hooks via `.nex/plugins/`. Events: `onToolResult`, `onModelResponse`, `onSessionStart`, `onSessionEnd`, `onFileChange`, `beforeToolExec`, `afterToolExec`.
1301
323
 
1302
- Skills are loaded on startup. All enabled by default. Disabled skills tracked in `.nex/config.json`.
324
+ ### MCP
1303
325
 
1304
- ### Global Skills (`~/.nex-code/skills/`)
326
+ Connect external tool servers via [Model Context Protocol](https://modelcontextprotocol.io). Configure in `.nex/mcp.json` with env var interpolation.
1305
327
 
1306
- Skills placed in `~/.nex-code/skills/` are loaded globally across all projects. Useful for cross-project workflows.
328
+ ### Hooks
1307
329
 
1308
- **Example: `server-agent.md`** — instructs nex-code on your Mac to delegate tasks to a nex-code instance on a remote server using the `remote_agent` tool. Define a project→server mapping table in the skill so the agent knows which path to use for each project name.
1309
-
1310
- ### Skill Marketplace
1311
-
1312
- Install community skills directly from git:
1313
-
1314
- ```
1315
- /install-skill https://github.com/user/nex-skill-deploy
1316
- /install-skill user/nex-skill-deploy # shorthand
1317
- /search-skill kubernetes # search GitHub
1318
- /remove-skill deploy # uninstall
1319
- ```
1320
-
1321
- Skills are cloned to `.nex/skills/{name}/` and validated (must contain `skill.json`, `.md`, or `.js` files).
1322
-
1323
- ### Built-in Skills
1324
-
1325
- nex-code ships with built-in skills in `cli/skills/`:
1326
-
1327
- - **devops** — DevOps agent instructions for SSH, Docker, deploy, and infrastructure tools
1328
-
1329
- Built-in skills are loaded automatically. Project skills with the same name override built-ins.
1330
-
1331
- ---
1332
-
1333
- ## Plugins
1334
-
1335
- Extend nex-code with custom tools and lifecycle hooks via `.nex/plugins/`:
1336
-
1337
- ```javascript
1338
- // .nex/plugins/my-plugin.js
1339
- module.exports = function setup(api) {
1340
- api.registerTool(
1341
- {
1342
- type: "function",
1343
- function: {
1344
- name: "my_tool",
1345
- description: "Custom tool",
1346
- parameters: { type: "object", properties: {} },
1347
- },
1348
- },
1349
- async (args) => {
1350
- return "result";
1351
- },
1352
- );
1353
-
1354
- api.registerHook("onToolResult", (data) => {
1355
- console.log(`Tool ${data.tool} completed`);
1356
- return data;
1357
- });
1358
- };
1359
- ```
1360
-
1361
- **Events:** `onToolResult`, `onModelResponse`, `onSessionStart`, `onSessionEnd`, `onFileChange`, `beforeToolExec`, `afterToolExec`
1362
-
1363
- Plugins are loaded automatically on startup. Hook handlers can modify event data (return the modified object).
1364
-
1365
- ---
1366
-
1367
- ## Audit Logging
1368
-
1369
- When `NEX_AUDIT=1` is set, all tool executions are logged to `.nex/audit/YYYY-MM-DD.jsonl`:
1370
-
1371
- ```
1372
- /audit # show summary (total calls, success rate, per-tool breakdown)
1373
- ```
1374
-
1375
- Arguments are automatically sanitized — keys matching `key`, `token`, `password`, `secret`, or `credential` are masked. Long values (>500 chars) are truncated.
1376
-
1377
- ---
1378
-
1379
- ## Safety
1380
-
1381
- nex-code includes multi-layer protections to prevent accidental damage — even in `--auto` and `--yolo` mode:
1382
-
1383
- | Layer | What it guards | Bypass possible? |
1384
- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------ |
1385
- | **Forbidden patterns** | `rm -rf /`, fork bombs, reverse shells, `cat .env` | No |
1386
- | **Protected paths** | Destructive bash ops (`rm`, `mv`, `truncate`, …) on `.env`, `credentials/`, `venv/`, `.ssh/`, `.aws/`, `.sqlite3`, `.git/` internals | Only via `NEX_UNPROTECT=1` |
1387
- | **Sensitive file tools** | `read_file` / `write_file` / `edit_file` on `.env`, `.ssh/`, `.npmrc`, `.kube/config`, etc. | No |
1388
- | **Critical commands** | `rm -rf`, `sudo`, `git push --force`, `git reset --hard` | Requires explicit confirmation |
1389
-
1390
- **Override:** If you intentionally need to modify a protected path via bash (e.g. rotating credentials in a deploy script), set `NEX_UNPROTECT=1`:
1391
-
1392
- ```bash
1393
- NEX_UNPROTECT=1 nex-code
1394
- ```
1395
-
1396
- This disables the protected-path check only — forbidden patterns and critical-command prompts remain active.
1397
-
1398
- ### Reporting Vulnerabilities
1399
-
1400
- If you discover a security vulnerability, please report it responsibly:
1401
-
1402
- - **Do not** open a public GitHub issue
1403
- - Email: **security@schoensgibl.com**
1404
- - Include: description, reproduction steps, and potential impact
1405
- - Allow up to 72 hours for initial response
1406
-
1407
- ---
1408
-
1409
- ## Team Permissions
1410
-
1411
- Permission presets for team environments:
1412
-
1413
- | Preset | Description |
1414
- | ----------- | -------------------------------------------------- |
1415
- | `readonly` | Search and read tools only — no writes, no deploys |
1416
- | `developer` | All tools except deploy, ssh_exec, service_manage |
1417
- | `admin` | Full access to all tools |
1418
-
1419
- Configure in `.nex/config.json`:
1420
-
1421
- ```json
1422
- {
1423
- "permissionPreset": "developer"
1424
- }
1425
- ```
1426
-
1427
- Works alongside the existing per-tool `/allow` and `/deny` system.
1428
-
1429
- ---
1430
-
1431
- ## MCP
1432
-
1433
- Connect external tool servers via the [Model Context Protocol](https://modelcontextprotocol.io):
1434
-
1435
- ```json
1436
- // .nex/config.json
1437
- {
1438
- "mcpServers": {
1439
- "my-server": {
1440
- "command": "node",
1441
- "args": ["path/to/server.js"]
1442
- }
1443
- }
1444
- }
1445
- ```
1446
-
1447
- ```
1448
- /mcp # show servers and tools
1449
- /mcp connect # connect all configured servers
1450
- /mcp disconnect # disconnect all
1451
- ```
1452
-
1453
- MCP tools appear with the `mcp_` prefix and are available to the agent alongside built-in tools.
330
+ Run custom scripts on CLI events (`pre-tool`, `post-tool`, `pre-commit`, `post-response`, `session-start`, `session-end`). Configure in `.nex/config.json` or `.nex/hooks/`.
1454
331
 
1455
332
  ---
1456
333
 
1457
- ## MCP Servers
1458
-
1459
- nex-code supports a dedicated `.nex/mcp.json` file (or `~/.nex/mcp.json` for global config) for
1460
- connecting MCP tool servers. This format supports environment variable interpolation so you can keep
1461
- API keys out of the config file.
1462
-
1463
- ```json
1464
- // .nex/mcp.json
1465
- {
1466
- "servers": {
1467
- "brave-search": {
1468
- "command": "npx",
1469
- "args": ["-y", "@modelcontextprotocol/server-brave-search"],
1470
- "env": { "BRAVE_API_KEY": "${BRAVE_API_KEY}" }
1471
- },
1472
- "filesystem": {
1473
- "command": "npx",
1474
- "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
1475
- }
1476
- }
1477
- }
1478
- ```
1479
-
1480
- **Search order for config:** `.nex/mcp.json` → `~/.nex/mcp.json`. Override with `--mcp-config <path>`.
1481
-
1482
- **Slash commands:**
1483
-
1484
- ```
1485
- /mcp list — list connected MCP servers and their exposed tools
1486
- /mcp status — show which servers are running / stopped
1487
- ```
1488
-
1489
- **How it works:**
1490
-
1491
- 1. nex-code spawns each server as a child process using stdio JSON-RPC transport.
1492
- 2. It sends `initialize` + `tools/list` to discover available tools.
1493
- 3. All discovered tools are merged into the nex-code tool registry under the name `mcp_<server>_<tool>`.
1494
- 4. The agent can call them transparently alongside built-in tools.
1495
- 5. All server processes are shut down cleanly when nex-code exits.
334
+ ## VS Code Extension
1496
335
 
1497
- **Env var interpolation:** `${VAR}` in the `env` block is replaced from `process.env` at startup so you
1498
- can store the actual key in your shell environment or `.env` file:
336
+ Built-in sidebar chat panel (`vscode/`) with streaming output, collapsible tool cards, and native theme support. Spawns `nex-code --server` over JSON-lines IPC.
1499
337
 
1500
338
  ```bash
1501
- export BRAVE_API_KEY=my-key
1502
- nex-code --mcp-config .nex/mcp.json
1503
- ```
1504
-
1505
- ---
1506
-
1507
- ## Hooks
1508
-
1509
- Run custom scripts on CLI events:
1510
-
1511
- ```json
1512
- // .nex/config.json
1513
- {
1514
- "hooks": {
1515
- "pre-tool": ["echo 'before tool'"],
1516
- "post-tool": ["echo 'after tool'"],
1517
- "pre-commit": ["npm test"]
1518
- }
1519
- }
1520
- ```
1521
-
1522
- Events: `pre-tool`, `post-tool`, `pre-commit`, `post-response`, `session-start`, `session-end`.
1523
-
1524
- Or place executable scripts in `.nex/hooks/`:
1525
-
1526
- ```
1527
- .nex/hooks/pre-tool
1528
- .nex/hooks/post-tool
339
+ cd vscode && npm install && npm run package
340
+ # Cmd+Shift+P → Extensions: Install from VSIX...
1529
341
  ```
1530
342
 
1531
343
  ---
@@ -1533,161 +345,43 @@ Or place executable scripts in `.nex/hooks/`:
1533
345
  ## Architecture
1534
346
 
1535
347
  ```
1536
- bin/nex-code.js # Entrypoint (shebang, .env, startREPL)
348
+ bin/nex-code.js # Entrypoint
1537
349
  cli/
1538
- ├── index.js # REPL + ~45 slash commands + history persistence + AbortController
1539
- ├── agent.js # Agentic loop + conversation state + compact output + résumé + abort handling
1540
- ├── providers/ # Multi-provider abstraction
1541
- │ ├── base.js # Abstract provider interface
1542
- │ ├── ollama.js # Ollama Cloud provider
1543
- │ ├── openai.js # OpenAI provider
1544
- │ ├── anthropic.js # Anthropic provider
1545
- │ ├── gemini.js # Google Gemini provider
1546
- │ ├── local.js # Local Ollama server
1547
- │ └── registry.js # Provider registry + model resolution + provider routing
1548
- ├── tools.js # 45 tool definitions + implementations + auto-fix engine
1549
- ├── sub-agent.js # Parallel sub-agent runner with file locking + model routing
1550
- ├── tasks.js # Task list management (create, update, render, onChange callbacks)
1551
- ├── skills.js # Skills system (prompt + script + marketplace)
1552
- ├── plugins.js # Plugin API (registerTool, registerHook, event system)
1553
- ├── audit.js # Tool execution audit logging (JSONL + sanitization)
1554
- ├── mcp.js # MCP client (JSON-RPC over stdio)
1555
- ├── hooks.js # Hook system (pre/post events)
1556
- ├── context.js # Auto-context (package.json, git, README) + generateFileTree()
1557
- ├── context-engine.js # Token management + relevance-based context compression
1558
- ├── session.js # Session persistence (.nex/sessions/)
1559
- ├── memory.js # Project memory (.nex/memory/ + NEX.md)
1560
- ├── filelock.js # Inter-process file locking (atomicWrite + withFileLockSync)
1561
- ├── permissions.js # Tool permission system + team presets (readonly/developer/admin)
1562
- ├── planner.js # Plan mode, step extraction, step cursor, autonomy levels
1563
- ├── git.js # Git intelligence (commit, diff, branch)
1564
- ├── render.js # Markdown + syntax highlighting + StreamRenderer + EPIPE guard
1565
- ├── format.js # Tool call formatting, result formatting, compact summaries
1566
- ├── spinner.js # Spinner, MultiProgress, TaskProgress, ToolProgress display components
1567
- ├── diff.js # LCS diff (Myers + Hirschberg) + colored output + side-by-side view
1568
- ├── fuzzy-match.js # Fuzzy text matching for edit auto-fix (Levenshtein, whitespace normalization)
1569
- ├── file-history.js # Persistent undo/redo + named git snapshots + blob storage
1570
- ├── picker.js # Interactive terminal picker (model selection)
1571
- ├── costs.js # Token cost tracking + per-provider budget limits
1572
- ├── safety.js # Forbidden/dangerous pattern detection
1573
- ├── tool-validator.js # Tool argument validation + auto-correction
1574
- ├── tool-tiers.js # Dynamic tool set selection per model + model tier lookup + edit mode
1575
- ├── footer.js # Sticky footer (scroll region, status bar, input row, resize, FOOTER_DEBUG)
1576
- ├── ui.js # ANSI colors, banner + re-exports from format.js/spinner.js
1577
- ├── index-engine.js # In-memory file index (ripgrep/fallback) + semantic content index
1578
- ├── skills/devops.md # Built-in DevOps agent skill
1579
- ├── auto-fix.js # Path resolution, edit matching, bash error hints
1580
- ├── tool-retry.js # Malformed argument retry with schema hints
1581
- └── ollama.js # Backward-compatible wrapper
350
+ agent.js # Agentic loop + conversation state + guards
351
+ providers/ # Ollama, OpenAI, Anthropic, Gemini, Local + wire protocols
352
+ tools/index.js # 45 tool definitions + auto-fix engine
353
+ context-engine.js # Token management + 5-phase compression
354
+ sub-agent.js # Parallel sub-agents with file locking
355
+ orchestrator.js # Multi-agent decompose → execute → synthesize
356
+ session-tree.js # Session branching
357
+ visual.js # Visual dev tools (pixelmatch-based)
358
+ browser.js # Playwright browser agent
359
+ skills/ # Built-in + user skills
1582
360
  ```
1583
361
 
1584
- ### Agentic Loop
1585
-
1586
- ```
1587
- User Input --> [AbortController created]
1588
- |
1589
- [System Prompt + Context + Memory + Skills + Conversation]
1590
- |
1591
- [Filter tools by model tier (essential/standard/full)]
1592
- |
1593
- Provider API (streaming + abort signal) --> Text tokens --> rendered to terminal
1594
- | \--> Tool calls --> parse args (5 strategies)
1595
- | |
1596
- | [Validate against schema + auto-correct]
1597
- | |
1598
- | Execute (skill / MCP / built-in)
1599
- | |
1600
- | [Auto-fix: path resolution, edit matching, bash hints]
1601
- |
1602
- [Tool results added to history]
1603
- |
1604
- Loop until: no more tool calls OR 50 iterations OR Ctrl+C abort
1605
- ```
1606
-
1607
- ---
1608
-
1609
- ## .nex/ Directory
1610
-
1611
- Project-local configuration and state (gitignored):
1612
-
1613
- ```
1614
- .nex/
1615
- ├── config.json # Permissions, MCP servers, hooks, skills, cost limits
1616
- ├── sessions/ # Saved conversations
1617
- ├── memory/ # Persistent project knowledge
1618
- ├── plans/ # Saved plans
1619
- ├── hooks/ # Custom hook scripts
1620
- ├── skills/ # Skill files (.md and .js)
1621
- └── push-allowlist # False-positive allowlist for pre-push secret detection
1622
- ```
1623
-
1624
- ---
1625
-
1626
- ## Performance
1627
-
1628
- Nex Code v0.3.45+ includes comprehensive performance optimizations:
1629
-
1630
- | Optimization | Improvement | Impact |
1631
- | ---------------------------- | --------------- | ------------------------- |
1632
- | **System Prompt Caching** | 4.3× faster | 77µs → 18µs |
1633
- | **Token Estimation Caching** | 3.5× faster | Cached after first call |
1634
- | **Context File Caching** | 10-20× faster | 50-200ms → 5-10ms |
1635
- | **Debounced Auto-Save** | 0ms in hot path | Saves after 5s inactivity |
1636
- | **Tool Filter Caching** | 1.7× faster | Cached per model |
1637
- | **Schema Cache** | 3.4× faster | 2.51µs → 0.73µs |
1638
-
1639
- **Average speedup:** 2.7× (micro-benchmarks)
1640
- **Real-world improvement:** ~10× faster per turn
1641
-
1642
- Run benchmarks yourself:
1643
-
1644
- ```bash
1645
- node benchmark.js
1646
- ```
362
+ See [DEVELOPMENT.md](DEVELOPMENT.md) for full architecture details.
1647
363
 
1648
364
  ---
1649
365
 
1650
366
  ## Testing
1651
367
 
1652
368
  ```bash
1653
- npm test # Run all tests with coverage
1654
- npm run test:watch # Watch mode
369
+ npm test # 97 suites, 3920 tests
370
+ npm run typecheck # TypeScript noEmit check
371
+ npm run benchmark:gate # 7-task smoke test (blocks push on regression)
372
+ npm run benchmark:reallife # 35 real-world tasks across 7 categories
1655
373
  ```
1656
374
 
1657
- 91 test suites, 3719 tests, 83% statement / 74% branch coverage.
1658
-
1659
- CI runs on GitHub Actions (Node 20 LTS).
1660
-
1661
- **Type checking:** `npm run typecheck` runs TypeScript in `noEmit` mode with `allowJs`. Core type definitions live in `types/index.d.ts` (Message, ToolCall, IProvider, IWireProtocol, Session, Skill, etc.). The codebase uses incremental TypeScript adoption — new modules can be written in `.ts` while existing `.js` files are gradually migrated.
1662
-
1663
375
  ---
1664
376
 
1665
- ## Dependencies
1666
-
1667
- 2 runtime dependencies:
1668
-
1669
- ```json
1670
- {
1671
- "axios": "^1.7.0",
1672
- "dotenv": "^16.4.0"
1673
- }
1674
- ```
1675
-
1676
- Everything else is Node.js built-in.
1677
-
1678
- ## Installation
1679
-
1680
- ```bash
1681
- npm install -g nex-code # global install
1682
- npx nex-code # or run without installing
1683
- ```
1684
-
1685
- On first launch with no API keys configured, nex-code starts an **interactive setup wizard** that guides you through choosing a provider and entering credentials. You can re-run it anytime with `/setup`.
1686
-
1687
- ## Roadmap
377
+ ## Security
1688
378
 
1689
- See [ROADMAP.md](ROADMAP.md) for planned features — VS Code extension, browser agent, PTY support, and more.
1690
- Community contributions are welcome on all roadmap items.
379
+ - Pre-push secret detection (API keys, private keys, hardcoded credentials)
380
+ - Audit logging with automatic argument sanitization
381
+ - Sensitive path blocking (`.ssh/`, `.aws/`, `.env`, credentials)
382
+ - Shell injection protection via `execFileSync` with argument arrays throughout
383
+ - SSRF protection on `web_fetch`
384
+ - MCP environment isolation
1691
385
 
1692
386
  ---
1693
387