nex-code 0.3.77 → 0.3.84

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 (4) hide show
  1. package/README.md +402 -219
  2. package/dist/bundle.js +19330 -247
  3. package/dist/nex-code.js +708 -632
  4. package/package.json +5 -3
package/README.md CHANGED
@@ -24,11 +24,11 @@
24
24
  </p>
25
25
 
26
26
  ---
27
+
27
28
  ## Demo
28
29
 
29
30
  https://github.com/user-attachments/assets/6a70525c-a1a4-4c6f-9784-176cb1becc15
30
31
 
31
-
32
32
  ---
33
33
 
34
34
  ## Quickstart
@@ -58,6 +58,7 @@ Nex Code automatically checks for new versions when you start it. If a newer ver
58
58
  ```
59
59
 
60
60
  To update to the latest version:
61
+
61
62
  ```bash
62
63
  npm update -g nex-code
63
64
  ```
@@ -74,19 +75,20 @@ npm update -g nex-code
74
75
 
75
76
  **Smart model routing.** The built-in `/benchmark` system tests all configured models against 33 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:
76
77
 
77
- | Detected task | Routed model (example) |
78
- |---|---|
79
- | Frontend / CSS / React | `qwen3-coder:480b` |
80
- | Sysadmin / Docker / nginx | `devstral-2:123b` |
81
- | Data / SQL / migrations | `devstral-2:123b` |
82
- | Agentic swarms | `minimax-m2.7:cloud` |
83
- | General coding | `devstral-2:123b` (default) |
78
+ | Detected task | Routed model (example) |
79
+ | ------------------------- | --------------------------- |
80
+ | Frontend / CSS / React | `qwen3-coder:480b` |
81
+ | Sysadmin / Docker / nginx | `devstral-2:123b` |
82
+ | Data / SQL / migrations | `devstral-2:123b` |
83
+ | Agentic swarms | `minimax-m2.7:cloud` |
84
+ | General coding | `devstral-2:123b` (default) |
84
85
 
85
86
  **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.
86
87
 
87
88
  **Lightweight.** 2 runtime dependencies (`axios`, `dotenv`). Starts in ~100ms. No Python, no heavy runtime, no daemon process.
88
89
 
89
90
  **Infrastructure tools built in:**
91
+
90
92
  - SSH server management (AlmaLinux, macOS, any Linux)
91
93
  - Docker tools — local and remote via SSH
92
94
  - Kubernetes overview (`/k8s`)
@@ -96,6 +98,7 @@ npm update -g nex-code
96
98
  - Grounded web search via Perplexity or DuckDuckGo
97
99
 
98
100
  **Developer safety:**
101
+
99
102
  - Pre-push secret detection — blocks commits that contain API keys or tokens
100
103
  - Full audit log (JSONL + sanitization)
101
104
  - Undo/Redo with persistence across restarts
@@ -118,16 +121,17 @@ Rankings are based on nex-code's own `/benchmark` — 15 tool-calling tasks agai
118
121
  <!-- nex-benchmark-start -->
119
122
  <!-- Updated: 2026-03-20 — run `/benchmark --discover` after new Ollama Cloud releases -->
120
123
 
121
- | Rank | Model | Score | Avg Latency | Context | Best For |
122
- |---|---|---|---|---|---|
123
- | 🥇 | `devstral-2:123b` | **84** | 1.5s | 131K | Default — fastest + most reliable tool selection |
124
- | 🥈 | `qwen3-coder:480b` | 79 | 2.9s | 131K | Coding-heavy sessions, heavy sub-agents |
125
- | 🥉 | `kimi-k2:1t` | 79 | 2.7s | 256K | Large repos (>100K tokens) |
126
- | — | `minimax-m2.7:cloud` | 73 | 3.5s | 200K | Complex swarm / multi-agent sessions (Toolathon SOTA) |
127
- | — | `devstral-small-2:24b` | 73 | 1.0s | 131K | Fast sub-agents, simple lookups |
124
+ | Rank | Model | Score | Avg Latency | Context | Best For |
125
+ | ---- | ---------------------- | ------ | ----------- | ------- | ----------------------------------------------------- |
126
+ | 🥇 | `devstral-2:123b` | **84** | 1.5s | 131K | Default — fastest + most reliable tool selection |
127
+ | 🥈 | `qwen3-coder:480b` | 79 | 2.9s | 131K | Coding-heavy sessions, heavy sub-agents |
128
+ | 🥉 | `kimi-k2:1t` | 79 | 2.7s | 256K | Large repos (>100K tokens) |
129
+ | — | `minimax-m2.7:cloud` | 73 | 3.5s | 200K | Complex swarm / multi-agent sessions (Toolathon SOTA) |
130
+ | — | `devstral-small-2:24b` | 73 | 1.0s | 131K | Fast sub-agents, simple lookups |
128
131
 
129
132
  > Rankings are nex-code-specific: tool name accuracy, argument validity, schema compliance.
130
133
  > Toolathon (Minimax SOTA) measures different task types — run `/benchmark --discover` after model releases.
134
+
131
135
  <!-- nex-benchmark-end -->
132
136
 
133
137
  ### Recommended `.env` for Ollama Cloud (Flat-Rate)
@@ -160,6 +164,7 @@ Auto-discovery runs weekly via the scheduled improvement task and updates this t
160
164
  ## Setup
161
165
 
162
166
  ### Prerequisites
167
+
163
168
  - Node.js 18+
164
169
  - At least one API key **or** a local [Ollama](https://ollama.com/download) server
165
170
 
@@ -234,6 +239,7 @@ You should see the banner, your project context, and the `>` prompt.
234
239
  ### Try These Scenarios
235
240
 
236
241
  **Understand an unfamiliar codebase:**
242
+
237
243
  ```
238
244
  > give me an overview of this project — architecture, key files, tech stack
239
245
  > how does authentication work here? trace the flow from login to session
@@ -241,6 +247,7 @@ You should see the banner, your project context, and the `>` prompt.
241
247
  ```
242
248
 
243
249
  **Fix bugs with context:**
250
+
244
251
  ```
245
252
  > the /users endpoint returns 500 — find the bug and fix it
246
253
  > tests are failing in auth.test.js — figure out why and fix it
@@ -248,6 +255,7 @@ You should see the banner, your project context, and the `>` prompt.
248
255
  ```
249
256
 
250
257
  **Add features end-to-end:**
258
+
251
259
  ```
252
260
  > add rate limiting to all API routes (100 req/min per IP)
253
261
  > add a /health endpoint that checks DB connectivity
@@ -255,6 +263,7 @@ You should see the banner, your project context, and the `>` prompt.
255
263
  ```
256
264
 
257
265
  **Refactor and improve:**
266
+
258
267
  ```
259
268
  > refactor the database queries to use a connection pool
260
269
  > this function is 200 lines — break it into smaller functions
@@ -262,6 +271,7 @@ You should see the banner, your project context, and the `>` prompt.
262
271
  ```
263
272
 
264
273
  **DevOps and CI:**
274
+
265
275
  ```
266
276
  > write a Dockerfile for this project
267
277
  > set up GitHub Actions CI that runs tests on push
@@ -269,9 +279,11 @@ You should see the banner, your project context, and the `>` prompt.
269
279
  ```
270
280
 
271
281
  **Multi-step autonomous work (YOLO mode):**
282
+
272
283
  ```bash
273
284
  nex-code -yolo
274
285
  ```
286
+
275
287
  ```
276
288
  > read the entire src/ directory, run the tests, fix all failures, then commit
277
289
  > add input validation to every POST endpoint, add tests, run them
@@ -281,10 +293,12 @@ nex-code -yolo
281
293
  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.
282
294
 
283
295
  **Vision / Screenshot → Code** — drop an image path anywhere in your message and nex-code will send it to a vision-capable model automatically:
296
+
284
297
  ```
285
298
  > /path/to/screenshot.png implement this UI in React
286
299
  > describe the layout in mockup.png and generate the CSS
287
300
  ```
301
+
288
302
  Supported formats: PNG, JPG, GIF, WebP, BMP. Works with Anthropic, OpenAI, Gemini, and Ollama vision models (llava, qwen2-vl, etc.).
289
303
 
290
304
  ### YOLO Mode
@@ -294,6 +308,7 @@ Skip all confirmation prompts — file changes, dangerous commands, and tool per
294
308
  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.
295
309
 
296
310
  You can also enable YOLO mode permanently for a project via `.nex/config.json`:
311
+
297
312
  ```json
298
313
  { "yolo": true }
299
314
  ```
@@ -317,17 +332,20 @@ nex-code --prompt-file /tmp/task.txt --yolo --json
317
332
  # → {"success":true,"response":"..."}
318
333
  ```
319
334
 
320
- | Flag | Description |
321
- |------|-------------|
322
- | `--task <prompt>` | Run a single prompt and exit |
323
- | `--prompt-file <path>` | Read prompt from a UTF-8 file and run headless |
324
- | `--delete-prompt-file` | Delete the prompt file after reading (use with `--prompt-file`) |
325
- | `--auto` | Skip confirmations (non-interactive, no REPL banner) |
326
- | `--yolo` | Skip all confirmations including dangerous commands (also configurable via `.nex/config.json` `"yolo": true`) |
327
- | `--server` | Start JSON-lines IPC server (used by the VS Code extension) |
328
- | `--json` | Output `{"success":true,"response":"..."}` to stdout |
329
- | `--max-turns <n>` | Override the agentic loop iteration limit |
330
- | `--model <spec>` | Use a specific model (e.g. `anthropic:claude-sonnet-4-6`) |
335
+ | Flag | Description |
336
+ | ---------------------- | ------------------------------------------------------------------------------------------------------------- |
337
+ | `--task <prompt>` | Run a single prompt and exit |
338
+ | `--prompt-file <path>` | Read prompt from a UTF-8 file and run headless |
339
+ | `--delete-prompt-file` | Delete the prompt file after reading (use with `--prompt-file`) |
340
+ | `--auto` | Skip confirmations (non-interactive, no REPL banner) |
341
+ | `--yolo` | Skip all confirmations including dangerous commands (also configurable via `.nex/config.json` `"yolo": true`) |
342
+ | `--server` | Start JSON-lines IPC server (used by the VS Code extension) |
343
+ | `--json` | Output `{"success":true,"response":"..."}` to stdout |
344
+ | `--max-turns <n>` | Override the agentic loop iteration limit |
345
+ | `--model <spec>` | Use a specific model (e.g. `anthropic:claude-sonnet-4-6`) |
346
+ | `--debug` | Show internal diagnostic messages (compression, loop detection, guards) |
347
+ | `--auto-orchestrate` | Automatically use the multi-agent orchestrator when ≥3 goals are detected (also: `NEX_AUTO_ORCHESTRATE=true`) |
348
+ | `--orchestrator-model <m>` | Model for decomposition/synthesis step (default: `kimi-k2.5`) |
331
349
 
332
350
  ---
333
351
 
@@ -340,6 +358,7 @@ nex-code ships with a built-in VS Code extension (`vscode/`) — no separate rep
340
358
  **Requirements:** nex-code must be in `$PATH` — either `npm install -g nex-code` or `npm link` for local development.
341
359
 
342
360
  **Install:**
361
+
343
362
  ```bash
344
363
  cd vscode
345
364
  npm install
@@ -349,23 +368,23 @@ npm run package # syncs version, builds, and creates .vsix
349
368
 
350
369
  **Settings** (`Settings → Extensions → Nex Code`):
351
370
 
352
- | Setting | Default | Description |
353
- |---------|---------|-------------|
354
- | `nexCode.executablePath` | `nex-code` | Path to the nex-code binary |
355
- | `nexCode.defaultProvider` | `ollama` | LLM provider |
356
- | `nexCode.defaultModel` | `devstral-2:123b` | Model name |
357
- | `nexCode.anthropicApiKey` | — | Anthropic API key |
358
- | `nexCode.openaiApiKey` | — | OpenAI API key |
359
- | `nexCode.ollamaApiKey` | — | Ollama Cloud API key |
360
- | `nexCode.geminiApiKey` | — | Google Gemini API key |
361
- | `nexCode.maxTurns` | `50` | Max agentic loop iterations |
371
+ | Setting | Default | Description |
372
+ | ------------------------- | ----------------- | --------------------------- |
373
+ | `nexCode.executablePath` | `nex-code` | Path to the nex-code binary |
374
+ | `nexCode.defaultProvider` | `ollama` | LLM provider |
375
+ | `nexCode.defaultModel` | `devstral-2:123b` | Model name |
376
+ | `nexCode.anthropicApiKey` | — | Anthropic API key |
377
+ | `nexCode.openaiApiKey` | — | OpenAI API key |
378
+ | `nexCode.ollamaApiKey` | — | Ollama Cloud API key |
379
+ | `nexCode.geminiApiKey` | — | Google Gemini API key |
380
+ | `nexCode.maxTurns` | `50` | Max agentic loop iterations |
362
381
 
363
382
  **Commands** (`Cmd+Shift+P`):
364
383
 
365
- | Command | Description |
366
- |---------|-------------|
367
- | `Nex Code: Clear Chat` | Clear conversation history |
368
- | `Nex Code: Switch Model` | Pick a different model |
384
+ | Command | Description |
385
+ | ------------------------- | ----------------------------------------------------- |
386
+ | `Nex Code: Clear Chat` | Clear conversation history |
387
+ | `Nex Code: Switch Model` | Pick a different model |
369
388
  | `Nex Code: Restart Agent` | Restart the child process (e.g. after source changes) |
370
389
 
371
390
  ---
@@ -383,15 +402,16 @@ Switch providers and models at runtime:
383
402
  /providers # see all available providers & models
384
403
  ```
385
404
 
386
- | Provider | Models | Env Variable |
387
- |----------|--------|-------------|
388
- | **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` |
389
- | **openai** | GPT-4o, GPT-4.1, o1, o3, o4-mini | `OPENAI_API_KEY` |
390
- | **anthropic** | Claude Sonnet 4.6, Opus 4.6, Haiku 4.5, Sonnet 4.5, Sonnet 4 | `ANTHROPIC_API_KEY` |
391
- | **gemini** | Gemini 3.1 Pro Preview, 2.5 Pro/Flash, 1.5 Pro/Flash | `GEMINI_API_KEY` |
392
- | **local** | Any model on your local Ollama server | (none) |
405
+ | Provider | Models | Env Variable |
406
+ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
407
+ | **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` |
408
+ | **openai** | GPT-4o, GPT-4.1, o1, o3, o4-mini | `OPENAI_API_KEY` |
409
+ | **anthropic** | Claude Sonnet 4.6, Opus 4.6, Haiku 4.5, Sonnet 4.5, Sonnet 4 | `ANTHROPIC_API_KEY` |
410
+ | **gemini** | Gemini 3.1 Pro Preview, 2.5 Pro/Flash, 1.5 Pro/Flash | `GEMINI_API_KEY` |
411
+ | **local** | Any model on your local Ollama server | (none) |
393
412
 
394
413
  Fallback chains let you auto-switch when a provider fails:
414
+
395
415
  ```
396
416
  /fallback anthropic,openai,local
397
417
  ```
@@ -402,64 +422,64 @@ Fallback chains let you auto-switch when a provider fails:
402
422
 
403
423
  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).
404
424
 
405
- | Command | Description |
406
- |---------|-------------|
407
- | `/help` | Full help |
408
- | `/model [spec]` | Show/switch model (e.g. `openai:gpt-4o`) |
409
- | `/providers` | List all providers and models |
410
- | `/fallback [chain]` | Show/set fallback chain |
411
- | `/tokens` | Token usage and context budget |
412
- | `/costs` | Session token costs |
413
- | `/budget` | Show/set per-provider cost limits |
414
- | `/clear` | Clear conversation |
415
- | `/context` | Show project context |
416
- | `/autoconfirm` | Toggle auto-confirm for file changes |
417
- | `/save [name]` | Save current session |
418
- | `/load <name>` | Load a saved session |
419
- | `/sessions` | List saved sessions |
420
- | `/resume` | Resume last session |
421
- | `/remember <text>` | Save a memory (persists across sessions) |
422
- | `/forget <key>` | Delete a memory |
423
- | `/memory` | Show all memories |
424
- | `/brain add <name>` | Add a document to the knowledge base |
425
- | `/brain list` | List all brain documents |
426
- | `/brain search <query>` | Search the knowledge base |
427
- | `/brain show <name>` | Show a brain document |
428
- | `/brain remove <name>` | Remove a brain document |
429
- | `/brain rebuild` | Rebuild keyword index |
430
- | `/brain embed` | Build/rebuild embedding index |
431
- | `/brain status` | Show brain status (docs, index, embeddings) |
432
- | `/brain review` | Review pending brain changes (git diff) |
433
- | `/brain undo` | Undo last brain write |
434
- | `/learn` | Reflect on session and auto-update memory + NEX.md |
435
- | `/permissions` | Show tool permissions |
436
- | `/allow <tool>` | Auto-allow a tool |
437
- | `/deny <tool>` | Block a tool |
438
- | `/plan [task]` | Plan mode (analyze before executing) |
439
- | `/plan edit` | Open current plan in `$EDITOR` for review/modification |
440
- | `/plans` | List saved plans |
441
- | `/auto [level]` | Set autonomy: interactive/semi-auto/autonomous |
442
- | `/commit [msg]` | Smart commit (analyze diff, suggest message) |
443
- | `/diff` | Show current diff |
444
- | `/branch [name]` | Create feature branch |
445
- | `/mcp` | MCP servers and tools |
446
- | `/hooks` | Show configured hooks |
447
- | `/skills` | List, enable, disable skills |
448
- | `/tree [depth]` | Show project file tree (default depth 3) |
449
- | `/undo` | Undo last file change |
450
- | `/redo` | Redo last undone change |
451
- | `/history` | Show file change history |
452
- | `/snapshot [name]` | Create a named git snapshot of current changes |
453
- | `/restore [name\|last]` | Restore a previously created snapshot |
454
- | `/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. |
455
- | `/k8s [user@host]` | Kubernetes overview: namespaces + pod health (remote via SSH optional) |
456
- | `/setup` | Interactive setup wizard — configure provider, API keys, web search |
457
- | `/benchmark [--quick\|--discover\|--history]` | Rank models on nex-code tool-calling tasks, auto-update routing |
458
- | `/install-skill <url>` | Install a skill from a git repo |
459
- | `/search-skill <query>` | Search GitHub for nex-code skills |
460
- | `/remove-skill <name>` | Remove an installed skill |
461
- | `/audit` | Show tool execution audit summary |
462
- | `/exit` | Quit |
425
+ | Command | Description |
426
+ | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
427
+ | `/help` | Full help |
428
+ | `/model [spec]` | Show/switch model (e.g. `openai:gpt-4o`) |
429
+ | `/providers` | List all providers and models |
430
+ | `/fallback [chain]` | Show/set fallback chain |
431
+ | `/tokens` | Token usage and context budget |
432
+ | `/costs` | Session token costs |
433
+ | `/budget` | Show/set per-provider cost limits |
434
+ | `/clear` | Clear conversation |
435
+ | `/context` | Show project context |
436
+ | `/autoconfirm` | Toggle auto-confirm for file changes |
437
+ | `/save [name]` | Save current session |
438
+ | `/load <name>` | Load a saved session |
439
+ | `/sessions` | List saved sessions |
440
+ | `/resume` | Resume last session |
441
+ | `/remember <text>` | Save a memory (persists across sessions) |
442
+ | `/forget <key>` | Delete a memory |
443
+ | `/memory` | Show all memories |
444
+ | `/brain add <name>` | Add a document to the knowledge base |
445
+ | `/brain list` | List all brain documents |
446
+ | `/brain search <query>` | Search the knowledge base |
447
+ | `/brain show <name>` | Show a brain document |
448
+ | `/brain remove <name>` | Remove a brain document |
449
+ | `/brain rebuild` | Rebuild keyword index |
450
+ | `/brain embed` | Build/rebuild embedding index |
451
+ | `/brain status` | Show brain status (docs, index, embeddings) |
452
+ | `/brain review` | Review pending brain changes (git diff) |
453
+ | `/brain undo` | Undo last brain write |
454
+ | `/learn` | Reflect on session and auto-update memory + NEX.md |
455
+ | `/permissions` | Show tool permissions |
456
+ | `/allow <tool>` | Auto-allow a tool |
457
+ | `/deny <tool>` | Block a tool |
458
+ | `/plan [task]` | Plan mode (analyze before executing) |
459
+ | `/plan edit` | Open current plan in `$EDITOR` for review/modification |
460
+ | `/plans` | List saved plans |
461
+ | `/auto [level]` | Set autonomy: interactive/semi-auto/autonomous |
462
+ | `/commit [msg]` | Smart commit (analyze diff, suggest message) |
463
+ | `/diff` | Show current diff |
464
+ | `/branch [name]` | Create feature branch |
465
+ | `/mcp` | MCP servers and tools |
466
+ | `/hooks` | Show configured hooks |
467
+ | `/skills` | List, enable, disable skills |
468
+ | `/tree [depth]` | Show project file tree (default depth 3) |
469
+ | `/undo` | Undo last file change |
470
+ | `/redo` | Redo last undone change |
471
+ | `/history` | Show file change history |
472
+ | `/snapshot [name]` | Create a named git snapshot of current changes |
473
+ | `/restore [name\|last]` | Restore a previously created snapshot |
474
+ | `/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. |
475
+ | `/k8s [user@host]` | Kubernetes overview: namespaces + pod health (remote via SSH optional) |
476
+ | `/setup` | Interactive setup wizard — configure provider, API keys, web search |
477
+ | `/benchmark [--quick\|--discover\|--history]` | Rank models on nex-code tool-calling tasks, auto-update routing |
478
+ | `/install-skill <url>` | Install a skill from a git repo |
479
+ | `/search-skill <query>` | Search GitHub for nex-code skills |
480
+ | `/remove-skill <name>` | Remove an installed skill |
481
+ | `/audit` | Show tool execution audit summary |
482
+ | `/exit` | Quit |
463
483
 
464
484
  ---
465
485
 
@@ -468,85 +488,94 @@ Type `/` to see inline suggestions as you type. Tab completion is supported for
468
488
  The agent has 45 built-in tools:
469
489
 
470
490
  ### Core & File System
471
- | Tool | Description |
472
- |------|-------------|
473
- | `bash` | Execute shell commands (90s timeout, 5MB buffer) |
474
- | `read_file` | Read files with optional line range (binary detection) |
475
- | `write_file` | Create or overwrite files (with diff preview + confirmation) |
476
- | `edit_file` | Targeted text replacement (with diff preview + confirmation) |
477
- | `patch_file` | Atomic multi-replacement in a single operation |
478
- | `list_directory` | Tree view with depth control and glob filtering |
479
- | `search_files` | Regex search across files (like grep) |
480
- | `glob` | Fast file search by name/extension pattern |
481
- | `grep` | Content search with regex and line numbers |
491
+
492
+ | Tool | Description |
493
+ | ---------------- | ------------------------------------------------------------ |
494
+ | `bash` | Execute shell commands (90s timeout, 5MB buffer) |
495
+ | `read_file` | Read files with optional line range (binary detection) |
496
+ | `write_file` | Create or overwrite files (with diff preview + confirmation) |
497
+ | `edit_file` | Targeted text replacement (with diff preview + confirmation) |
498
+ | `patch_file` | Atomic multi-replacement in a single operation |
499
+ | `list_directory` | Tree view with depth control and glob filtering |
500
+ | `search_files` | Regex search across files (like grep) |
501
+ | `glob` | Fast file search by name/extension pattern |
502
+ | `grep` | Content search with regex and line numbers |
482
503
 
483
504
  ### Git & Web
484
- | Tool | Description |
485
- |------|-------------|
486
- | `git_status` | Git working tree status |
487
- | `git_diff` | Git diff with optional path filter |
488
- | `git_log` | Git commit history with configurable count |
489
- | `web_fetch` | Fetch content from a URL |
505
+
506
+ | Tool | Description |
507
+ | ------------ | -------------------------------------------------------------------------- |
508
+ | `git_status` | Git working tree status |
509
+ | `git_diff` | Git diff with optional path filter |
510
+ | `git_log` | Git commit history with configurable count |
511
+ | `web_fetch` | Fetch content from a URL |
490
512
  | `web_search` | Grounded search via Perplexity (if `PERPLEXITY_API_KEY` set) or DuckDuckGo |
491
513
 
492
514
  ### Interaction & Agents
493
- | Tool | Description |
494
- |------|-------------|
495
- | `ask_user` | Ask the user a question and wait for input |
496
- | `task_list` | Create and manage task lists for multi-step operations |
497
- | `spawn_agents` | Run parallel sub-agents with auto model routing |
498
- | `switch_model` | Switch active model mid-conversation |
515
+
516
+ | Tool | Description |
517
+ | -------------- | ------------------------------------------------------ |
518
+ | `ask_user` | Ask the user a question and wait for input |
519
+ | `task_list` | Create and manage task lists for multi-step operations |
520
+ | `spawn_agents` | Run parallel sub-agents with auto model routing |
521
+ | `switch_model` | Switch active model mid-conversation |
499
522
 
500
523
  ### Browser (optional — requires Playwright)
501
- | Tool | Description |
502
- |------|-------------|
503
- | `browser_open` | Open URL in headless browser, return text + links (JS-heavy pages) |
504
- | `browser_screenshot` | Screenshot a URL → saved file + vision-ready path |
505
- | `browser_click` | Click element by CSS selector or visible text |
506
- | `browser_fill` | Fill form field and optionally submit |
524
+
525
+ | Tool | Description |
526
+ | -------------------- | ------------------------------------------------------------------ |
527
+ | `browser_open` | Open URL in headless browser, return text + links (JS-heavy pages) |
528
+ | `browser_screenshot` | Screenshot a URL → saved file + vision-ready path |
529
+ | `browser_click` | Click element by CSS selector or visible text |
530
+ | `browser_fill` | Fill form field and optionally submit |
507
531
 
508
532
  ### GitHub Actions
509
- | Tool | Description |
510
- |------|-------------|
511
- | `gh_run_list` | List GitHub Actions workflow runs |
512
- | `gh_run_view` | View run details and step logs |
513
- | `gh_workflow_trigger` | Trigger a workflow dispatch event |
514
- | `k8s_pods` | List Kubernetes pods (local kubectl or remote via SSH) |
515
- | `k8s_logs` | Fetch pod logs with `--tail` / `--since` filtering |
516
- | `k8s_exec` | Run a command inside a pod (with confirmation) |
517
- | `k8s_apply` | Apply a manifest file — `dry_run` mode supported (with confirmation) |
518
- | `k8s_rollout` | Rollout status / restart / history / undo for deployments |
533
+
534
+ | Tool | Description |
535
+ | --------------------- | -------------------------------------------------------------------- |
536
+ | `gh_run_list` | List GitHub Actions workflow runs |
537
+ | `gh_run_view` | View run details and step logs |
538
+ | `gh_workflow_trigger` | Trigger a workflow dispatch event |
539
+ | `k8s_pods` | List Kubernetes pods (local kubectl or remote via SSH) |
540
+ | `k8s_logs` | Fetch pod logs with `--tail` / `--since` filtering |
541
+ | `k8s_exec` | Run a command inside a pod (with confirmation) |
542
+ | `k8s_apply` | Apply a manifest file — `dry_run` mode supported (with confirmation) |
543
+ | `k8s_rollout` | Rollout status / restart / history / undo for deployments |
519
544
 
520
545
  ### SSH & Server Management
546
+
521
547
  Requires `.nex/servers.json` — run `/init` to configure. See [Server Management](#server-management).
522
548
 
523
- | Tool | Description |
524
- |------|-------------|
525
- | `ssh_exec` | Execute a command on a remote server via SSH |
526
- | `ssh_upload` | Upload a file or directory via SCP |
527
- | `ssh_download` | Download a file or directory via SCP |
528
- | `service_manage` | Start/stop/restart/reload/enable/disable a systemd service (local or remote) |
529
- | `service_logs` | Fetch journalctl logs (local or remote, with `--since` support) |
530
- | `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. |
531
- | `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. |
549
+ | Tool | Description |
550
+ | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
551
+ | `ssh_exec` | Execute a command on a remote server via SSH |
552
+ | `ssh_upload` | Upload a file or directory via SCP |
553
+ | `ssh_download` | Download a file or directory via SCP |
554
+ | `service_manage` | Start/stop/restart/reload/enable/disable a systemd service (local or remote) |
555
+ | `service_logs` | Fetch journalctl logs (local or remote, with `--since` support) |
556
+ | `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. |
557
+ | `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. |
532
558
 
533
559
  ### Docker
534
- | Tool | Description |
535
- |------|-------------|
536
- | `container_list` | List Docker containers (local or remote via SSH) |
537
- | `container_logs` | Fetch Docker container logs (`--tail`, `--since`) |
538
- | `container_exec` | Execute a command inside a running container |
539
- | `container_manage` | Start/stop/restart/remove/inspect a container |
560
+
561
+ | Tool | Description |
562
+ | ------------------ | ------------------------------------------------- |
563
+ | `container_list` | List Docker containers (local or remote via SSH) |
564
+ | `container_logs` | Fetch Docker container logs (`--tail`, `--since`) |
565
+ | `container_exec` | Execute a command inside a running container |
566
+ | `container_manage` | Start/stop/restart/remove/inspect a container |
540
567
 
541
568
  ### Deploy
542
- | Tool | Description |
543
- |------|-------------|
544
- | `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`. |
545
- | `deployment_status` | Check deployment health across all configured servers — server reachability, service status, health checks. Reads `.nex/deploy.json`. |
569
+
570
+ | Tool | Description |
571
+ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
572
+ | `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`. |
573
+ | `deployment_status` | Check deployment health across all configured servers — server reachability, service status, health checks. Reads `.nex/deploy.json`. |
546
574
 
547
575
  ### Frontend Design
548
- | Tool | Description |
549
- |------|-------------|
576
+
577
+ | Tool | Description |
578
+ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
550
579
  | `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. |
551
580
 
552
581
  **Interactive commands** (vim, top, htop, ssh, tmux, fzf, etc.) are automatically detected and spawned with full TTY passthrough — no separate handling required.
@@ -592,6 +621,7 @@ Or create `.nex/servers.json` manually:
592
621
  **OS values**: `almalinux9`, `almalinux8`, `ubuntu`, `debian`, `macos`
593
622
 
594
623
  When `.nex/servers.json` exists, the agent automatically receives OS-aware context:
624
+
595
625
  - **AlmaLinux 9**: `dnf`, `firewalld`, `systemctl`, SELinux hints
596
626
  - **macOS**: `brew`, `launchctl`, `log show` instead of `journalctl`
597
627
 
@@ -599,18 +629,18 @@ If the project also has a `NEX.md` containing deployment indicators (`ssh`, `ser
599
629
 
600
630
  ### Slash Commands
601
631
 
602
- | Command | Description |
603
- |---------|-------------|
604
- | `/servers` | List all configured server profiles |
605
- | `/servers ping` | Check SSH connectivity for all servers in parallel |
606
- | `/servers ping <name>` | Check a specific server |
607
- | `/docker` | List running containers across all servers + local |
608
- | `/docker -a` | Include stopped containers |
609
- | `/deploy` | List all named deploy configs |
610
- | `/deploy <name>` | Run a named deploy (with confirmation) |
611
- | `/deploy <name> --dry-run` | Preview without syncing |
612
- | `/init` | Interactive wizard: create `.nex/servers.json` |
613
- | `/init deploy` | Interactive wizard: create `.nex/deploy.json` |
632
+ | Command | Description |
633
+ | -------------------------- | -------------------------------------------------- |
634
+ | `/servers` | List all configured server profiles |
635
+ | `/servers ping` | Check SSH connectivity for all servers in parallel |
636
+ | `/servers ping <name>` | Check a specific server |
637
+ | `/docker` | List running containers across all servers + local |
638
+ | `/docker -a` | Include stopped containers |
639
+ | `/deploy` | List all named deploy configs |
640
+ | `/deploy <name>` | Run a named deploy (with confirmation) |
641
+ | `/deploy <name> --dry-run` | Preview without syncing |
642
+ | `/init` | Interactive wizard: create `.nex/servers.json` |
643
+ | `/init deploy` | Interactive wizard: create `.nex/deploy.json` |
614
644
 
615
645
  ### Named Deploy Configs
616
646
 
@@ -639,11 +669,13 @@ Create `.nex/deploy.json` (or use `/init deploy`):
639
669
  ```
640
670
 
641
671
  Then deploy with:
672
+
642
673
  ```
643
674
  > /deploy prod
644
675
  ```
645
676
 
646
677
  Or from within a conversation:
678
+
647
679
  ```
648
680
  deploy the latest build to prod
649
681
  ```
@@ -653,7 +685,9 @@ deploy the latest build to prod
653
685
  ## Features
654
686
 
655
687
  ### Compact Output
688
+
656
689
  The agent loop uses a bouncing-ball spinner (`● · · · ·` → `· ● · · ·` → …) during tool execution, then prints compact 1-line summaries:
690
+
657
691
  ```
658
692
  ● ▸ 3 tools: read_file, grep, edit_file
659
693
  ✓ read_file src/app.js (45 lines)
@@ -662,15 +696,18 @@ The agent loop uses a bouncing-ball spinner (`● · · · ·` → `· ● · ·
662
696
  ```
663
697
 
664
698
  After multi-step tasks, a résumé and context-aware follow-up suggestions are shown:
699
+
665
700
  ```
666
701
  ── 3 steps · 8 tools · 2 files modified · 37s ──
667
702
  💡 /diff · /commit · /undo
668
703
  ```
704
+
669
705
  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.
670
706
 
671
707
  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.
672
708
 
673
709
  ### Response Quality
710
+
674
711
  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.
675
712
 
676
713
  **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.
@@ -678,18 +715,23 @@ The system prompt enforces substantive responses: the model always presents find
678
715
  **Code examples:** The model is instructed to always show actual, working code — never pseudocode or placeholder snippets.
679
716
 
680
717
  ### Performance
718
+
681
719
  - **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.
682
720
  - **Fast Startup**: Pre-bundled with `esbuild` to minimize module loading overhead, achieving sub-100ms startup times.
683
721
  - **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.
684
722
 
685
723
  ### Streaming Output
724
+
686
725
  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).
687
726
 
688
727
  ### Paste Detection
728
+
689
729
  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.
690
730
 
691
731
  ### Ctrl+C Cancellation
732
+
692
733
  Pressing Ctrl+C during a running request immediately cancels the active HTTP stream and returns to the prompt:
734
+
693
735
  - An `AbortController` signal flows from the readline SIGINT handler through the agent loop to the provider's HTTP request
694
736
  - All providers (Ollama, OpenAI, Anthropic, Gemini, local) destroy the response stream on abort
695
737
  - No EPIPE errors after cancellation (stdout writes are EPIPE-guarded)
@@ -698,7 +740,9 @@ Pressing Ctrl+C during a running request immediately cancels the active HTTP str
698
740
  - readline intercepts Ctrl+C on TTY (`rl.on('SIGINT')`) to prevent readline close → `process.exit(0)` race
699
741
 
700
742
  ### Diff Preview
743
+
701
744
  Every file change is shown in a diff-style format before being applied:
745
+
702
746
  - **Header**: `⏺ Update(file)` or `⏺ Create(file)` with relative path
703
747
  - **Summary**: `⎿ Added N lines, removed M lines`
704
748
  - **Numbered lines**: right-justified line numbers with red `-` / green `+` markers
@@ -707,12 +751,14 @@ Every file change is shown in a diff-style format before being applied:
707
751
  - All changes require `[y/n]` confirmation (toggle with `/autoconfirm` or start with `-yolo`)
708
752
 
709
753
  ### Terminal Theme Detection
754
+
710
755
  Nex Code automatically adapts all colours to your terminal's background:
711
756
 
712
757
  - **Dark terminals** — bright, saturated palette with `\x1b[2m` dim for muted text
713
758
  - **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
714
759
 
715
760
  Detection priority:
761
+
716
762
  1. `NEX_THEME=light|dark` env var — explicit override, useful if auto-detection is wrong
717
763
  2. `COLORFGBG` env var — set by iTerm2 and other terminals
718
764
  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.
@@ -721,7 +767,9 @@ Detection priority:
721
767
  If you use multiple Apple Terminal profiles (e.g. white, dark teal, dark green), each window is detected independently — no manual configuration needed.
722
768
 
723
769
  ### Auto-Context
770
+
724
771
  On startup, the CLI reads your project and injects context into the system prompt:
772
+
725
773
  - `package.json` — name, version, scripts, dependencies
726
774
  - `README.md` — first 50 lines
727
775
  - Git info — branch, status, recent commits
@@ -729,10 +777,13 @@ On startup, the CLI reads your project and injects context into the system promp
729
777
  - **Merge conflicts** — detected and shown as a red warning; included in LLM context so the agent avoids editing conflicted files
730
778
 
731
779
  ### Context Engine
780
+
732
781
  Automatic token management with compression when the context window gets full. Tracks token usage across system prompt, conversation, tool results, and tool definitions.
733
782
 
734
783
  ### Safety Layer
784
+
735
785
  Three tiers of protection:
786
+
736
787
  - **Forbidden** (blocked): `rm -rf /`, `rm -rf .`, `mkfs`, `dd if=`, fork bombs, `curl|sh`, `cat .env`, `chmod 777`, reverse shells — 30+ patterns
737
788
  - **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
738
789
  - **Notable** (confirmation on first use): `git push`, `npm publish`, `ssh`, `HUSKY=0`, `SKIP_HUSKY=1` — first-time prompt, then respects "always allow"
@@ -746,6 +797,7 @@ Three tiers of protection:
746
797
  - **Post-merge automation**: Auto-bumps patch version on `devel→main` merge; runs `npm install` when `package.json` changes
747
798
 
748
799
  ### Sessions
800
+
749
801
  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:
750
802
 
751
803
  ```
@@ -756,12 +808,12 @@ Only sessions from the last 24 hours are offered for auto-resume. Older autosave
756
808
 
757
809
  **Session commands:**
758
810
 
759
- | Command | Description |
760
- |---------|-------------|
761
- | `/save <name>` | Save current conversation under a named slot |
762
- | `/load <name>` | Restore a previously saved session |
763
- | `/sessions` | List all saved sessions with message count and timestamp |
764
- | `/resume` | Resume the most recently saved session |
811
+ | Command | Description |
812
+ | -------------- | -------------------------------------------------------- |
813
+ | `/save <name>` | Save current conversation under a named slot |
814
+ | `/load <name>` | Restore a previously saved session |
815
+ | `/sessions` | List all saved sessions with message count and timestamp |
816
+ | `/resume` | Resume the most recently saved session |
765
817
 
766
818
  ```
767
819
  /save my-feature # save with name
@@ -773,7 +825,9 @@ Only sessions from the last 24 hours are offered for auto-resume. Older autosave
773
825
  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.
774
826
 
775
827
  ### Memory
828
+
776
829
  Persistent project memory that survives across sessions:
830
+
777
831
  ```
778
832
  /remember lang=TypeScript
779
833
  /remember always use yarn instead of npm
@@ -784,7 +838,9 @@ Persistent project memory that survives across sessions:
784
838
  Also loads `NEX.md` from project root for project-level instructions.
785
839
 
786
840
  ### Brain — Persistent Knowledge Base
841
+
787
842
  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:
843
+
788
844
  ```
789
845
  /brain add auth-flow # add a document (prompted for content)
790
846
  /brain search "jwt token" # keyword + semantic search
@@ -795,17 +851,21 @@ A project-scoped knowledge base stored in `.nex/brain/`. The agent automatically
795
851
  /brain review # git diff of recent brain writes
796
852
  /brain undo # undo last brain write
797
853
  ```
854
+
798
855
  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.
799
856
 
800
857
  ### Plan Mode
858
+
801
859
  Analyze before executing — the agent explores the codebase with read-only tools, produces a structured plan, then you approve before any changes are made.
802
860
 
803
861
  **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:
862
+
804
863
  ```
805
864
  > implement a search endpoint # → Auto Plan Mode activates immediately
806
865
  > refactor the auth module # → Auto Plan Mode activates immediately
807
866
  > how does auth work? # → normal mode (question, not implementation)
808
867
  ```
868
+
809
869
  Disable with `NEX_AUTO_PLAN=0` if you prefer manual control.
810
870
 
811
871
  ```
@@ -815,12 +875,15 @@ Disable with `NEX_AUTO_PLAN=0` if you prefer manual control.
815
875
  /plan approve # approve and exit plan mode (all tools re-enabled)
816
876
  /auto semi-auto # set autonomy level
817
877
  ```
878
+
818
879
  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.
819
880
 
820
881
  **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`.
821
882
 
822
883
  ### Snapshots
884
+
823
885
  Named git snapshots — save and restore working-tree state at any point:
886
+
824
887
  ```
825
888
  /snapshot before-refactor # create snapshot named "before-refactor"
826
889
  /snapshot list # list all saved snapshots
@@ -828,40 +891,52 @@ Named git snapshots — save and restore working-tree state at any point:
828
891
  /restore before-refactor # restore by name
829
892
  /restore list # show all available snapshots
830
893
  ```
894
+
831
895
  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.
832
896
 
833
897
  ### File Tree
898
+
834
899
  Visualize the project structure:
900
+
835
901
  ```
836
902
  /tree # show tree at depth 3
837
903
  /tree 2 # shallower view
838
904
  /tree 5 # deeper view (max 8)
839
905
  ```
906
+
840
907
  Automatically excludes `node_modules`, `.git`, `dist`, `build`, `coverage`, and all entries listed in `.gitignore`. Directories are sorted before files.
841
908
 
842
909
  ### Undo / Redo (Persistent)
910
+
843
911
  Undo/redo for all file changes (write, edit, patch) — **survives restart**:
912
+
844
913
  ```
845
914
  /undo # undo last file change
846
915
  /redo # redo last undone change
847
916
  /history # show file change history
848
917
  ```
918
+
849
919
  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.
850
920
 
851
921
  > **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.
852
922
 
853
923
  ### Desktop Notifications
924
+
854
925
  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.
855
926
 
856
927
  ### Task Management
928
+
857
929
  Create structured task lists for complex multi-step operations:
930
+
858
931
  ```
859
932
  /tasks # show current task list
860
933
  /tasks clear # clear all tasks
861
934
  ```
935
+
862
936
  The agent uses `task_list` to create, update, and track progress on tasks with dependency support.
863
937
 
864
938
  When the agent creates a task list, a **live animated display** replaces the static output:
939
+
865
940
  ```
866
941
  ✽ Adding cost limit functions… (1m 35s · ↓ 2.6k tokens)
867
942
  ⎿ ✔ Create cli/picker.js — Interactive Terminal Picker
@@ -870,22 +945,93 @@ When the agent creates a task list, a **live animated display** replaces the sta
870
945
  ◻ Update cli/index.js
871
946
  ◻ Run tests
872
947
  ```
948
+
873
949
  - Bouncing-ball spinner (`●` ping-pong across 5 positions) with elapsed time display
874
950
  - Per-task status icons: `✔` done, `◼` in progress, `◻` pending, `✗` failed
875
951
  - Automatically pauses during text streaming and resumes during tool execution
876
952
  - Falls back to the static `/tasks` view when no live display is active
877
953
 
878
954
  ### Sub-Agents
955
+
879
956
  Spawn parallel sub-agents for independent tasks:
957
+
880
958
  - Up to 5 agents run simultaneously with their own conversation contexts
881
959
  - File locking prevents concurrent writes to the same file (intra-process sub-agents)
882
960
  - Multi-progress display shows real-time status of each agent
883
961
  - Good for: reading multiple files, analyzing separate modules, independent research
884
962
 
963
+ ### Multi-Agent Orchestrator
964
+
965
+ 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.
966
+
967
+ **Trigger:**
968
+
969
+ ```bash
970
+ # One-off: pass flag on the CLI
971
+ nex-code --auto-orchestrate --task "fix all type errors in src/, add JSDoc to utils/, update CHANGELOG"
972
+
973
+ # Headless with custom orchestrator model
974
+ nex-code --auto-orchestrate --orchestrator-model kimi-k2.5 --task "..."
975
+
976
+ # Always-on via env var
977
+ NEX_AUTO_ORCHESTRATE=true nex-code
978
+
979
+ # Set minimum goal count before orchestrator activates (default: 3)
980
+ NEX_ORCHESTRATE_THRESHOLD=2 nex-code
981
+ ```
982
+
983
+ **Interactive:** type `/orchestrate <task>` at the prompt.
984
+
985
+ **Example output:**
986
+
987
+ ```
988
+ Orchestrator model: kimi-k2.5 | workers: devstral-2:123b | max parallel: 3
989
+
990
+ Phase 1: Decomposing prompt into sub-tasks...
991
+ Decomposed into 3 sub-tasks:
992
+ t1: Fix TypeScript errors in src/auth/
993
+ scope: src/auth/
994
+ t2: Add JSDoc comments to src/utils/
995
+ scope: src/utils/
996
+ t3: Update CHANGELOG with recent changes
997
+ scope: CHANGELOG.md
998
+
999
+ Phase 2: Running 3 sub-agents (max 3 parallel)...
1000
+
1001
+ ✓ Agent 1 [devstral-2:123b]: Fix TypeScript errors in src/auth/: fixed 4 type errors in login.ts, ...
1002
+ ✓ Agent 2 [devstral-2:123b]: Add JSDoc comments to src/utils/: documented 12 functions across 3 files
1003
+ ✓ Agent 3 [devstral-2:123b]: Update CHANGELOG: added entries for v1.2.0 changes
1004
+
1005
+ Phase 3: Synthesizing results...
1006
+
1007
+ Summary: Fixed 4 TS errors in auth module, added JSDoc to 12 utility functions, updated CHANGELOG.
1008
+ Suggested commit: fix: resolve auth type errors and add utility docs
1009
+ ```
1010
+
1011
+ **Env vars:**
1012
+
1013
+ | Variable | Default | Description |
1014
+ | ------------------------- | ------------- | -------------------------------------------------------- |
1015
+ | `NEX_AUTO_ORCHESTRATE` | `false` | Set to `true` to always use the orchestrator |
1016
+ | `NEX_ORCHESTRATE_THRESHOLD` | `3` | Minimum number of detected goals before auto-triggering |
1017
+
1018
+ **Model roles in orchestration:**
1019
+
1020
+ | Role | Default model | Purpose |
1021
+ | -------------- | ------------------- | -------------------------------------------- |
1022
+ | Orchestrator | `kimi-k2.5` | Decomposes prompt, synthesizes results |
1023
+ | Worker | `devstral-2:123b` | Executes each sub-task (one agent per task) |
1024
+
1025
+ Override via `--orchestrator-model` (orchestrator) or `DEFAULT_MODEL` / `NEX_STANDARD_MODEL` (workers).
1026
+
1027
+ ---
1028
+
885
1029
  ### Parallel Sessions
1030
+
886
1031
  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.
887
1032
 
888
1033
  **Multi-Model Routing** — Sub-agents auto-select the best model per task based on complexity:
1034
+
889
1035
  - **Read/search/list** tasks → fast models (essential tier)
890
1036
  - **Edit/fix/analyze** tasks → capable models (standard tier)
891
1037
  - **Refactor/implement/generate** tasks → most powerful models (full tier)
@@ -893,6 +1039,7 @@ Running multiple nex-code instances in the same project directory is safe. All s
893
1039
  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.
894
1040
 
895
1041
  ### Git Intelligence
1042
+
896
1043
  ```
897
1044
  /commit # analyze diff, suggest commit message
898
1045
  /commit feat: add login
@@ -901,7 +1048,9 @@ The LLM can also explicitly override with `model: "provider:model"` in the agent
901
1048
  ```
902
1049
 
903
1050
  ### Permissions
1051
+
904
1052
  Control which tools the agent can use:
1053
+
905
1054
  ```
906
1055
  /permissions # show current settings
907
1056
  /allow read_file # auto-allow without asking
@@ -911,14 +1060,18 @@ Control which tools the agent can use:
911
1060
  Persisted in `.nex/config.json`.
912
1061
 
913
1062
  ### Cost Tracking
1063
+
914
1064
  Track token usage and costs per provider:
1065
+
915
1066
  ```
916
1067
  /costs
917
1068
  /costs reset
918
1069
  ```
919
1070
 
920
1071
  ### Cost Limits
1072
+
921
1073
  Set per-provider spending limits. When a provider exceeds its budget, calls automatically fall back to the next provider in the fallback chain:
1074
+
922
1075
  ```
923
1076
  /budget # show all limits + current spend
924
1077
  /budget anthropic 5 # set $5 limit for Anthropic
@@ -927,6 +1080,7 @@ Set per-provider spending limits. When a provider exceeds its budget, calls auto
927
1080
  ```
928
1081
 
929
1082
  Limits are persisted in `.nex/config.json`. You can also set them directly:
1083
+
930
1084
  ```json
931
1085
  // .nex/config.json
932
1086
  {
@@ -948,22 +1102,26 @@ Four features that make Nex Code significantly more reliable with open-source mo
948
1102
  **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.
949
1103
 
950
1104
  **Auto-Fix Engine** — Three layers of automatic error recovery that silently fix common tool failures:
1105
+
951
1106
  - **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.
952
1107
  - **Edit auto-fix**: Close match (≤5% Levenshtein distance) in `edit_file`/`patch_file` is auto-applied instead of erroring. Stacks with fuzzy whitespace matching.
953
1108
  - **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.
954
1109
 
955
1110
  **Stale Stream Recovery** — Progressive retry strategy when streams stall (common with large Ollama models after many agent steps):
1111
+
956
1112
  - 1st retry: 3s backoff delay, resend same context (handles transient stalls)
957
1113
  - 2nd retry: force-compress conversation (~80k tokens freed), 5s delay, retry with smaller context
958
1114
  - Last resort: if retries exhausted, one final force-compress + reset for fresh attempts
959
1115
  - Broader context-too-long detection catches Ollama-specific error formats (`num_ctx`, `prompt`, `size`, `exceeds`)
960
1116
 
961
1117
  **Tool Tiers** — Dynamically reduces the tool set based on model capability:
1118
+
962
1119
  - **essential** (5 tools): bash, read_file, write_file, edit_file, list_directory
963
1120
  - **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
964
1121
  - **full** (45 tools): all tools
965
1122
 
966
1123
  Models are auto-classified, or override per-model in `.nex/config.json`:
1124
+
967
1125
  ```json
968
1126
  {
969
1127
  "toolTiers": {
@@ -986,35 +1144,49 @@ Tiers are also used by sub-agent routing — when a sub-agent auto-selects a mod
986
1144
  Extend Nex Code with project-specific knowledge, commands, and tools via `.nex/skills/`.
987
1145
 
988
1146
  ### Prompt Skills (`.md`)
1147
+
989
1148
  Drop a Markdown file and its content is injected into the system prompt:
990
1149
 
991
1150
  ```markdown
992
1151
  <!-- .nex/skills/code-style.md -->
1152
+
993
1153
  # Code Style
1154
+
994
1155
  - Always use semicolons
995
1156
  - Prefer const over let
996
1157
  - Use TypeScript strict mode
997
1158
  ```
998
1159
 
999
1160
  ### Script Skills (`.js`)
1161
+
1000
1162
  CommonJS modules that can provide instructions, slash commands, and tools:
1001
1163
 
1002
1164
  ```javascript
1003
1165
  // .nex/skills/deploy.js
1004
1166
  module.exports = {
1005
- name: 'deploy',
1006
- description: 'Deployment helper',
1007
- instructions: 'When deploying, always run tests first...',
1167
+ name: "deploy",
1168
+ description: "Deployment helper",
1169
+ instructions: "When deploying, always run tests first...",
1008
1170
  commands: [
1009
- { cmd: '/deploy', desc: 'Run deployment', handler: (args) => { /* ... */ } }
1171
+ {
1172
+ cmd: "/deploy",
1173
+ desc: "Run deployment",
1174
+ handler: (args) => {
1175
+ /* ... */
1176
+ },
1177
+ },
1010
1178
  ],
1011
1179
  tools: [
1012
1180
  {
1013
- type: 'function',
1014
- function: { name: 'deploy_status', description: 'Check status', parameters: { type: 'object', properties: {} } },
1015
- execute: async (args) => 'deployed'
1016
- }
1017
- ]
1181
+ type: "function",
1182
+ function: {
1183
+ name: "deploy_status",
1184
+ description: "Check status",
1185
+ parameters: { type: "object", properties: {} },
1186
+ },
1187
+ execute: async (args) => "deployed",
1188
+ },
1189
+ ],
1018
1190
  };
1019
1191
  ```
1020
1192
 
@@ -1050,6 +1222,7 @@ Skills are cloned to `.nex/skills/{name}/` and validated (must contain `skill.js
1050
1222
  ### Built-in Skills
1051
1223
 
1052
1224
  nex-code ships with built-in skills in `cli/skills/`:
1225
+
1053
1226
  - **devops** — DevOps agent instructions for SSH, Docker, deploy, and infrastructure tools
1054
1227
 
1055
1228
  Built-in skills are loaded automatically. Project skills with the same name override built-ins.
@@ -1063,14 +1236,21 @@ Extend nex-code with custom tools and lifecycle hooks via `.nex/plugins/`:
1063
1236
  ```javascript
1064
1237
  // .nex/plugins/my-plugin.js
1065
1238
  module.exports = function setup(api) {
1066
- api.registerTool({
1067
- type: 'function',
1068
- function: { name: 'my_tool', description: 'Custom tool', parameters: { type: 'object', properties: {} } }
1069
- }, async (args) => {
1070
- return 'result';
1071
- });
1072
-
1073
- api.registerHook('onToolResult', (data) => {
1239
+ api.registerTool(
1240
+ {
1241
+ type: "function",
1242
+ function: {
1243
+ name: "my_tool",
1244
+ description: "Custom tool",
1245
+ parameters: { type: "object", properties: {} },
1246
+ },
1247
+ },
1248
+ async (args) => {
1249
+ return "result";
1250
+ },
1251
+ );
1252
+
1253
+ api.registerHook("onToolResult", (data) => {
1074
1254
  console.log(`Tool ${data.tool} completed`);
1075
1255
  return data;
1076
1256
  });
@@ -1099,12 +1279,12 @@ Arguments are automatically sanitized — keys matching `key`, `token`, `passwor
1099
1279
 
1100
1280
  nex-code includes multi-layer protections to prevent accidental damage — even in `--auto` and `--yolo` mode:
1101
1281
 
1102
- | Layer | What it guards | Bypass possible? |
1103
- |---|---|---|
1104
- | **Forbidden patterns** | `rm -rf /`, fork bombs, reverse shells, `cat .env` | No |
1105
- | **Protected paths** | Destructive bash ops (`rm`, `mv`, `truncate`, …) on `.env`, `credentials/`, `venv/`, `.ssh/`, `.aws/`, `.sqlite3`, `.git/` internals | Only via `NEX_UNPROTECT=1` |
1106
- | **Sensitive file tools** | `read_file` / `write_file` / `edit_file` on `.env`, `.ssh/`, `.npmrc`, `.kube/config`, etc. | No |
1107
- | **Critical commands** | `rm -rf`, `sudo`, `git push --force`, `git reset --hard` | Requires explicit confirmation |
1282
+ | Layer | What it guards | Bypass possible? |
1283
+ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------ |
1284
+ | **Forbidden patterns** | `rm -rf /`, fork bombs, reverse shells, `cat .env` | No |
1285
+ | **Protected paths** | Destructive bash ops (`rm`, `mv`, `truncate`, …) on `.env`, `credentials/`, `venv/`, `.ssh/`, `.aws/`, `.sqlite3`, `.git/` internals | Only via `NEX_UNPROTECT=1` |
1286
+ | **Sensitive file tools** | `read_file` / `write_file` / `edit_file` on `.env`, `.ssh/`, `.npmrc`, `.kube/config`, etc. | No |
1287
+ | **Critical commands** | `rm -rf`, `sudo`, `git push --force`, `git reset --hard` | Requires explicit confirmation |
1108
1288
 
1109
1289
  **Override:** If you intentionally need to modify a protected path via bash (e.g. rotating credentials in a deploy script), set `NEX_UNPROTECT=1`:
1110
1290
 
@@ -1129,13 +1309,14 @@ If you discover a security vulnerability, please report it responsibly:
1129
1309
 
1130
1310
  Permission presets for team environments:
1131
1311
 
1132
- | Preset | Description |
1133
- |--------|-------------|
1134
- | `readonly` | Search and read tools only — no writes, no deploys |
1135
- | `developer` | All tools except deploy, ssh_exec, service_manage |
1136
- | `admin` | Full access to all tools |
1312
+ | Preset | Description |
1313
+ | ----------- | -------------------------------------------------- |
1314
+ | `readonly` | Search and read tools only — no writes, no deploys |
1315
+ | `developer` | All tools except deploy, ssh_exec, service_manage |
1316
+ | `admin` | Full access to all tools |
1137
1317
 
1138
1318
  Configure in `.nex/config.json`:
1319
+
1139
1320
  ```json
1140
1321
  {
1141
1322
  "permissionPreset": "developer"
@@ -1190,6 +1371,7 @@ Run custom scripts on CLI events:
1190
1371
  Events: `pre-tool`, `post-tool`, `pre-commit`, `post-response`, `session-start`, `session-end`.
1191
1372
 
1192
1373
  Or place executable scripts in `.nex/hooks/`:
1374
+
1193
1375
  ```
1194
1376
  .nex/hooks/pre-tool
1195
1377
  .nex/hooks/post-tool
@@ -1294,19 +1476,20 @@ Project-local configuration and state (gitignored):
1294
1476
 
1295
1477
  Nex Code v0.3.45+ includes comprehensive performance optimizations:
1296
1478
 
1297
- | Optimization | Improvement | Impact |
1298
- |--------------|-------------|--------|
1299
- | **System Prompt Caching** | 4.3× faster | 77µs → 18µs |
1300
- | **Token Estimation Caching** | 3.5× faster | Cached after first call |
1301
- | **Context File Caching** | 10-20× faster | 50-200ms → 5-10ms |
1302
- | **Debounced Auto-Save** | 0ms in hot path | Saves after 5s inactivity |
1303
- | **Tool Filter Caching** | 1.7× faster | Cached per model |
1304
- | **Schema Cache** | 3.4× faster | 2.51µs → 0.73µs |
1479
+ | Optimization | Improvement | Impact |
1480
+ | ---------------------------- | --------------- | ------------------------- |
1481
+ | **System Prompt Caching** | 4.3× faster | 77µs → 18µs |
1482
+ | **Token Estimation Caching** | 3.5× faster | Cached after first call |
1483
+ | **Context File Caching** | 10-20× faster | 50-200ms → 5-10ms |
1484
+ | **Debounced Auto-Save** | 0ms in hot path | Saves after 5s inactivity |
1485
+ | **Tool Filter Caching** | 1.7× faster | Cached per model |
1486
+ | **Schema Cache** | 3.4× faster | 2.51µs → 0.73µs |
1305
1487
 
1306
1488
  **Average speedup:** 2.7× (micro-benchmarks)
1307
1489
  **Real-world improvement:** ~10× faster per turn
1308
1490
 
1309
1491
  Run benchmarks yourself:
1492
+
1310
1493
  ```bash
1311
1494
  node benchmark.js
1312
1495
  ```