nex-code 0.3.13 → 0.3.18

package/README.md

@@ -8,17 +8,21 @@
 ```
 
 <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">
+  <img src="https://img.shields.io/badge/tests-1825-blue.svg" alt="Tests: 1825">
 </p>
 
 ---
@@ -64,15 +68,40 @@ 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** | ✅ | ❌ | ❌ | ❌ |
+| **Browser agent (headless)** | ✅ Playwright-based | ❌ | ⚠️ Experimental | ❌ |
+| **Grounded web search** | ✅ Perplexity/DDG | ❌ | ✅ Google grounded | ❌ |
+| **GitHub Actions tools** | ✅ native | ❌ | ❌ | ❌ |
+| **Open-source** | ✅ MIT | ❌ | ✅ Apache 2.0 | ✅ |
+| **Runtime dependencies** | **2** (axios, dotenv) | Many | Many | Heavy (Python) |
+| **Startup time** | **~100ms** | ~400ms | ~300ms | Slow |
+| **Test coverage** | 1825 tests, 84% | — | — | — |
+
+---
+
+## 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`.
 
 ---
 
@@ -116,6 +145,7 @@ OLLAMA_API_KEY=your-key       # Ollama Cloud (Qwen3 Coder, Qwen3.5, DeepSeek R1,
 OPENAI_API_KEY=your-key       # OpenAI (GPT-4o, GPT-4.1, o1, o3, o4-mini)
 ANTHROPIC_API_KEY=your-key    # Anthropic (Claude Sonnet 4.6, Opus 4.6, Haiku 4.5)
 GEMINI_API_KEY=your-key       # Google Gemini (3.1 Pro Preview, 2.5 Pro/Flash, 2.0 Flash)
+PERPLEXITY_API_KEY=your-key   # Perplexity (optional — enables grounded web search)
 # No key needed for local Ollama — just have it running
 ```
 
@@ -188,10 +218,47 @@ 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`.
 
+### Headless / Programmatic Mode
+
+Run nex-code non-interactively from scripts, CI pipelines, or other processes:
+
+```bash
+# Inline prompt
+nex-code --task "refactor src/index.js to use async/await" --yolo
+
+# Prompt from file (avoids shell-escaping issues with special characters)
+nex-code --prompt-file /tmp/task.txt --yolo
+
+# Delete the file after reading
+nex-code --prompt-file /tmp/task.txt --delete-prompt-file --yolo
+
+# JSON output for programmatic parsing
+nex-code --prompt-file /tmp/task.txt --yolo --json
+# → {"success":true,"response":"..."}
+```
+
+| Flag | Description |
+|------|-------------|
+| `--task <prompt>` | Run a single prompt and exit |
+| `--prompt-file <path>` | Read prompt from a UTF-8 file and run headless |
+| `--delete-prompt-file` | Delete the prompt file after reading (use with `--prompt-file`) |
+| `--auto` | Skip confirmations (non-interactive, no REPL banner) |
+| `--yolo` | Skip all confirmations including dangerous commands |
+| `--json` | Output `{"success":true,"response":"..."}` to stdout |
+| `--max-turns <n>` | Override the agentic loop iteration limit |
+| `--model <spec>` | Use a specific model (e.g. `anthropic:claude-sonnet-4-6`) |
+
 ---
 
 ## Providers & Models
@@ -260,6 +327,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 |
 
 ---
@@ -283,10 +351,21 @@ The agent has 17 built-in tools:
 | `git_diff` | Git diff with optional path filter |
 | `git_log` | Git commit history with configurable count |
 | `web_fetch` | Fetch content from a URL |
-| `web_search` | Search the web via DuckDuckGo |
+| `web_search` | Grounded search via Perplexity (if `PERPLEXITY_API_KEY` set) or DuckDuckGo |
 | `ask_user` | Ask the user a question and wait for input |
 | `task_list` | Create and manage task lists for multi-step operations |
 | `spawn_agents` | Run parallel sub-agents with auto model routing |
+| `browser_open` | Open URL in headless browser, return text + links (JS-heavy pages) |
+| `browser_screenshot` | Screenshot a URL → saved file + vision-ready path |
+| `browser_click` | Click element by CSS selector or visible text |
+| `browser_fill` | Fill form field and optionally submit |
+| `gh_run_list` | List GitHub Actions workflow runs |
+| `gh_run_view` | View run details and step logs |
+| `gh_workflow_trigger` | Trigger a workflow dispatch event |
+
+**Interactive commands** (vim, top, htop, ssh, tmux, fzf, etc.) are automatically detected and spawned with full TTY passthrough — no separate handling required.
+
+**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.
 
 Additional tools can be added via [MCP servers](#mcp) or [Skills](#skills).
 
@@ -746,7 +825,7 @@ npm test              # Run all tests with coverage
 npm run test:watch    # Watch mode
 ```
 
-44 test suites, 1752 tests, 85% statement / 79% branch coverage.
+47 test suites, 1825 tests, 84% statement / 77% branch coverage.
 
 CI runs on GitHub Actions (Node 18/20/22).
 
@@ -772,6 +851,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 -->