nex-code 0.3.11 → 0.3.14

package/README.md

@@ -8,14 +8,18 @@
 ```
 
 <p align="center">
-  <b>Agentic coding CLI — open-source and multi-provider.</b><br>
-  Use OpenAI, Anthropic, Google Gemini, Ollama Cloud, or local models. Your choice.
+  <b>The open-source coding CLI for Ollama Cloud — and every other provider.</b><br>
+  Free by default with Ollama. Switch to OpenAI, Anthropic, or Gemini anytime.<br>
+  A lightweight, powerful alternative to Claude Code and Gemini CLI.
 </p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/nex-code"><img src="https://img.shields.io/npm/v/nex-code.svg" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/nex-code"><img src="https://img.shields.io/npm/dm/nex-code.svg" alt="npm downloads"></a>
+  <a href="https://github.com/hybridpicker/nex-code/stargazers"><img src="https://img.shields.io/github/stars/hybridpicker/nex-code.svg" alt="GitHub Stars"></a>
   <a href="https://github.com/hybridpicker/nex-code/actions/workflows/ci.yml"><img src="https://github.com/hybridpicker/nex-code/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
+  <img src="https://img.shields.io/badge/Ollama_Cloud-supported-brightgreen.svg" alt="Ollama Cloud: supported">
   <img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg" alt="Node >= 18">
   <img src="https://img.shields.io/badge/dependencies-2-green.svg" alt="Dependencies: 2">
   <img src="https://img.shields.io/badge/tests-1752-blue.svg" alt="Tests: 1752">
@@ -64,15 +68,37 @@ npm update -g nex-code
 
 ## Why nex-code?
 
-| | nex-code | aider | Cursor |
-|---|---|---|---|
-| **Open-source** | MIT | Apache 2.0 | Proprietary |
-| **Multi-provider** | 5 providers, swap at runtime | Multi-provider | Multi-provider |
-| **Free local models** | Ollama (no API key) | Ollama | — |
-| **Runtime dependencies** | 2 (axios, dotenv) | Heavy | Electron |
-| **Test coverage** | 1752 tests, 85% coverage | — | — |
-| **Tool tiers** | Auto-adapts tools per model | Fixed | Fixed |
-| **No lock-in** | `/model openai:gpt-4o` ↔ `/model local:llama3` | Config change | Config change |
+| | **nex-code** | Claude Code | Gemini CLI | Aider |
+|---|---|---|---|---|
+| **Free with Ollama** | ✅ Native, first-class | ⚠️ Workaround | ❌ | ✅ |
+| **Ollama Cloud support** | ✅ 47+ models, native | ⚠️ API-compat only | ❌ | ✅ |
+| **Multi-provider runtime swap** | ✅ 5 providers, no restart | ❌ Claude-only | ❌ Gemini-only | ✅ |
+| **Tool tiers (adapts to model)** | ✅ essential/standard/full | ❌ | ❌ | ❌ |
+| **5-layer open-model auto-fix** | ✅ | ❌ | ❌ | ⚠️ |
+| **Undo / Redo** | ✅ | ❌ | ❌ | ❌ |
+| **Cost tracking + budgets** | ✅ | ❌ | ❌ | ❌ |
+| **Pre-push secret detection** | ✅ | ❌ | ❌ | ❌ |
+| **Open-source** | ✅ MIT | ❌ | ✅ Apache 2.0 | ✅ |
+| **Runtime dependencies** | **2** (axios, dotenv) | Many | Many | Heavy (Python) |
+| **Startup time** | **~100ms** | ~400ms | ~300ms | Slow |
+| **Test coverage** | 1752 tests, 85% | — | — | — |
+
+---
+
+## Ollama Cloud — The Free-by-Default Model Tier
+
+nex-code was built with Ollama Cloud as its primary provider. No subscription, no billing surprises.
+Use powerful open models like **Qwen3 Coder**, **Kimi K2.5**, **Devstral**, and **DeepSeek R1** for free.
+
+| Model | Context | Best For |
+|---|---|---|
+| `qwen3-coder:480b` | 131K | Code generation, tool calling |
+| `kimi-k2.5` | 256K | Large repos, reasoning |
+| `devstral-2:123b` | 131K | Reliable tool calling |
+| `devstral-small-2:24b` | 131K | Fast, efficient |
+| `qwen3.5:35b-a3b` | 256K | MoE, very fast |
+
+Switch anytime: `/model ollama:qwen3-coder:480b` or add your `OLLAMA_API_KEY` to `.env`.
 
 ---
 
@@ -188,6 +214,13 @@ nex-code -yolo
 
 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.
 
+**Vision / Screenshot → Code** — drop an image path anywhere in your message and nex-code will send it to a vision-capable model automatically:
+```
+> /path/to/screenshot.png implement this UI in React
+> describe the layout in mockup.png and generate the CSS
+```
+Supported formats: PNG, JPG, GIF, WebP, BMP. Works with Anthropic, OpenAI, Gemini, and Ollama vision models (llava, qwen2-vl, etc.).
+
 ### YOLO Mode
 
 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`.
@@ -260,6 +293,7 @@ Type `/` to see inline suggestions as you type. Tab completion is supported for
 | `/undo` | Undo last file change |
 | `/redo` | Redo last undone change |
 | `/history` | Show file change history |
+| `/review [file]` | Code review on current diff or a specific file |
 | `/exit` | Quit |
 
 ---
@@ -288,6 +322,8 @@ The agent has 17 built-in tools:
 | `task_list` | Create and manage task lists for multi-step operations |
 | `spawn_agents` | Run parallel sub-agents with auto model routing |
 
+**Interactive commands** (vim, top, htop, ssh, tmux, fzf, etc.) are automatically detected and spawned with full TTY passthrough — no separate handling required.
+
 Additional tools can be added via [MCP servers](#mcp) or [Skills](#skills).
 
 ---
@@ -328,11 +364,12 @@ Automatic bracketed paste mode: pasting multi-line text into the prompt is detec
 
 ### Ctrl+C Cancellation
 Pressing Ctrl+C during a running request immediately cancels the active HTTP stream and returns to the prompt:
-- An `AbortController` signal flows from the SIGINT handler through the agent loop to the provider's HTTP request
+- An `AbortController` signal flows from the readline SIGINT handler through the agent loop to the provider's HTTP request
 - All providers (Ollama, OpenAI, Anthropic, Gemini, local) destroy the response stream on abort
 - No EPIPE errors after cancellation (stdout writes are EPIPE-guarded)
-- 2x Ctrl+C during processing force-exits the process
+- During processing: first Ctrl+C aborts the task and returns to prompt; second Ctrl+C force-exits
 - At the idle prompt: first Ctrl+C shows `(Press Ctrl+C again to exit)`, second Ctrl+C exits (hint resets after 2 s)
+- readline intercepts Ctrl+C on TTY (`rl.on('SIGINT')`) to prevent readline close → `process.exit(0)` race
 
 ### Diff Preview
 Every file change is shown in a diff-style format before being applied:
@@ -384,13 +421,14 @@ Persistent project memory that survives across sessions:
 Also loads `NEX.md` from project root for project-level instructions.
 
 ### Plan Mode
-Analyze before executing — the agent creates a plan, you review and approve:
+Analyze before executing — the agent explores the codebase with read-only tools, produces a structured plan, then you approve before any changes are made:
 ```
-/plan refactor the auth module
-/plan status
-/plan approve
-/auto semi-auto      # set autonomy level
+/plan refactor the auth module   # enter plan mode
+/plan status                     # show plan progress
+/plan approve                    # approve and exit plan mode (all tools re-enabled)
+/auto semi-auto                  # set autonomy level
 ```
+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 — the LLM cannot make changes even if it tries. The plan text is saved to `.nex/plans/current-plan.md` for review.
 
 ### Undo / Redo
 In-session undo/redo for all file changes (write, edit, patch):
@@ -515,10 +553,13 @@ Models are auto-classified, or override per-model in `.nex/config.json`:
     "deepseek-r1": "essential",
     "local:*": "essential",
     "qwen3-coder": "full"
-  }
+  },
+  "maxIterations": 100
 }
 ```
 
+`maxIterations` sets the agentic loop limit project-wide (default: 50). The `--max-turns <n>` CLI flag overrides it per run.
+
 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.
 
 ---
@@ -767,6 +808,17 @@ npm install -g nex-code    # global install
 npx nex-code               # or run without installing
 ```
 
+## Roadmap
+
+See [ROADMAP.md](ROADMAP.md) for planned features — VS Code extension, browser agent, PTY support, and more.
+Community contributions are welcome on all roadmap items.
+
+---
+
 ## License
 
 MIT
+
+<!-- Keywords: ollama cli, ollama coding assistant, claude code alternative, gemini cli alternative,
+     agentic coding cli, open source ai terminal, free coding ai, qwen3 coder cli, devstral terminal,
+     kimi k2 cli, multi-provider ai cli, local llm coding tool -->