nex-code

Run 400B+ open coding models on your codebase — without the hardware bill.
Ollama Cloud first. OpenAI, Anthropic, and Gemini when you need them.

npx nex-code

If this saves you time, a star helps others find it.

--- ## Demo https://github.com/user-attachments/assets/68a6c134-2d13-4d66-bc5e-befea3acb794 --- ## Quickstart ```bash npx nex-code # or install globally: npm install -g nex-code && cd ~/your-project && nex-code ``` On first launch, an interactive setup wizard guides you through provider and credential configuration. Re-run anytime with `/setup`. --- ## Why nex-code? **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. | Feature | nex-code | Closed-source alternatives | |---|---|---| | Free tier | Ollama Cloud flat-rate | subscription or limited quota | | Open models | devstral, Kimi K2, Qwen3 | vendor-locked | | Local Ollama | yes | no | | Multi-provider | swap with one env var | no | | VS Code sidebar | built-in | partial | | Startup time | ~100ms | 1-4s | | Runtime deps | 2 | heavy | | Infra tools | SSH, Docker, K8s built-in | no | **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. **Phase-based execution.** Tasks run through Plan (analyze) -> Implement (code) -> Verify (test) phases, each with the optimal model. Auto-loops back on test failures. **45 built-in tools** across file ops, git, SSH, Docker, Kubernetes, deploy, browser, GitHub Actions, and visual review. **2 runtime dependencies** (`axios`, `dotenv`). Starts in ~100ms. No Python, no heavy runtime. --- ## Ollama Cloud Model Rankings Rankings from nex-code's own `/benchmark` — 62 tasks testing tool selection, argument validity, and schema compliance. | Rank | Model | Score | Latency | Context | Best For | |---|---|---|---|---|---| | 1 | `qwen3-vl:235b-instruct` | **79.9** | 3.8s | 131K | Best latency/score balance | | 2 | `qwen3-vl:235b` | 79.4 | 12.3s | 131K | Frontier tool selection | | 3 | `qwen3-coder-next` | 74.9 | 1.7s | 256K | — | | 4 | `ministral-3:8b` | 74.2 | 1.2s | 131K | Fastest strong model | | 5 | `devstral-2:123b` | 69.9 | 1.6s | 131K | Sysadmin/SSH, reliable | > Run `/benchmark --discover` to detect new models and auto-update this table. **Recommended `.env`:** ```env DEFAULT_PROVIDER=ollama DEFAULT_MODEL=devstral-2:123b NEX_HEAVY_MODEL=qwen3-coder:480b NEX_STANDARD_MODEL=devstral-2:123b NEX_FAST_MODEL=devstral-small-2:24b ``` --- ## Setup **Prerequisites:** Node.js 18+ and at least one API key (or local Ollama). ```bash # .env (or set environment variables) OLLAMA_API_KEY=your-key # Ollama Cloud OPENAI_API_KEY=your-key # OpenAI ANTHROPIC_API_KEY=your-key # Anthropic GEMINI_API_KEY=your-key # Gemini PERPLEXITY_API_KEY=your-key # optional — grounded web search DEFAULT_PROVIDER=ollama DEFAULT_MODEL=devstral-2:123b ``` **Install from source:** ```bash git clone https://github.com/hybridpicker/nex-code.git cd nex-code && npm install && npm run build cp .env.example .env && npm link && npm run install-hooks ``` --- ## Usage ``` > explain the main function in index.js > add input validation to the createUser handler > run the tests and fix any failures > the /users endpoint returns 500 — find the bug and fix it ``` **YOLO mode** — skip all confirmations, auto-runs `caffeinate` on macOS: ```bash nex-code -yolo ``` **Headless / Programmatic:** ```bash nex-code --task "refactor src/index.js to async/await" --yolo nex-code --prompt-file /tmp/task.txt --yolo --json nex-code --daemon # background watcher (reads .nex/daemon.json) ``` | Flag | Description | |---|---| | `--task ` | Run a single prompt and exit | | `--prompt-file ` | Read prompt from file | | `--yolo` | Skip all confirmations | | `--server` | JSON-lines IPC server (VS Code extension) | | `--daemon` | Background watcher (file changes, git commits, cron) | | `--flatrate` | 100 turns, 6 parallel agents, 5 retries | | `--json` | JSON output to stdout | | `--max-turns ` | Override agentic loop limit | | `--model ` | e.g. `anthropic:claude-sonnet-4-6` | | `--debug` | Show diagnostic messages | **Vision / Screenshot:** ``` > /path/to/screenshot.png implement this UI in React > analyze https://example.com/mockup.png and implement it > what's wrong with the layout in my clipboard # macOS clipboard > screenshot localhost:3000 and review the navbar spacing ``` Formats: PNG, JPG, GIF, WebP, BMP. Works with all providers that support vision. --- ## Providers & Models ``` /model # interactive picker /model openai:gpt-4o # switch directly /providers # list all /fallback anthropic,openai # auto-switch on failure ``` | Provider | Models | Env Variable | |---|---|---| | **ollama** | Qwen3, DeepSeek R1, Devstral, Kimi K2, MiniMax, GLM, Llama 4 | `OLLAMA_API_KEY` | | **openai** | GPT-4o, GPT-4.1, o1, o3, o4-mini | `OPENAI_API_KEY` | | **anthropic** | Claude Opus 4.6, Sonnet 4.6, Haiku 4.5 | `ANTHROPIC_API_KEY` | | **gemini** | Gemini 3.1 Pro, 2.5 Pro/Flash | `GEMINI_API_KEY` | | **local** | Any local Ollama model | (none) | --- ## Commands Type `/` for inline suggestions. Tab completion for commands and file paths. | Command | Description | |---|---| | `/help` | Full help | | `/model [spec]` / `/providers` | Switch model / list all | | `/clear` | Clear conversation | | `/save` / `/load` / `/sessions` / `/resume` | Session management | | `/branches` / `/fork` / `/switch-branch` / `/goto` | Session tree navigation | | `/remember` / `/forget` / `/memory` | Persistent memory | | `/brain add\|list\|search\|show\|remove` | Knowledge base | | `/plan [task]` / `/plan edit` / `/plan approve` | Plan mode | | `/commit [msg]` / `/diff` / `/branch` | Git intelligence | | `/undo` / `/redo` / `/history` | Persistent undo/redo | | `/snapshot [name]` / `/restore` | Git snapshots | | `/permissions` / `/allow` / `/deny` | Tool permissions | | `/costs` / `/budget` | Cost tracking and limits | | `/review [--strict]` | Deep code review | | `/benchmark` | Model ranking (62 tasks) | | `/autoresearch` / `/ar-self-improve` | Autonomous optimization loops | | `/servers` / `/docker` / `/deploy` / `/k8s` | Infrastructure management | | `/skills` / `/install-skill` / `/mcp` / `/hooks` | Extensibility | | `/tree [depth]` | Project file tree | | `/audit` | Tool execution audit | | `/setup` | Interactive setup wizard | --- ## Tools 45 built-in tools: **Core:** `bash`, `read_file`, `write_file`, `edit_file`, `patch_file`, `list_directory`, `search_files`, `glob`, `grep` **Git & Web:** `git_status`, `git_diff`, `git_log`, `web_fetch`, `web_search` **Agents:** `ask_user`, `task_list`, `spawn_agents`, `switch_model` **Browser** (optional, requires Playwright): `browser_open`, `browser_screenshot`, `browser_click`, `browser_fill` **GitHub Actions & K8s:** `gh_run_list`, `gh_run_view`, `gh_workflow_trigger`, `k8s_pods`, `k8s_logs`, `k8s_exec`, `k8s_apply`, `k8s_rollout` **SSH & Server:** `ssh_exec`, `ssh_upload`, `ssh_download`, `service_manage`, `service_logs`, `sysadmin`, `remote_agent` **Docker:** `container_list`, `container_logs`, `container_exec`, `container_manage` **Deploy:** `deploy`, `deployment_status` **Frontend:** `frontend_recon` — scans design tokens, layout, and framework stack before any frontend work **Visual:** `visual_diff`, `responsive_sweep`, `visual_annotate`, `visual_watch`, `design_tokens`, `design_compare` Additional tools via [MCP servers](#mcp) or [Skills](#skills). --- ## Key Features ### Multi-Agent Orchestrator Multi-goal prompts auto-decompose into parallel sub-agents (up to 5 simultaneously, with file locking): ```bash nex-code --task "fix type errors in src/, add JSDoc to utils/, update CHANGELOG" ``` ### Autoresearch Autonomous optimization loops — edit → experiment → keep/revert, on a dedicated git branch: ``` /autoresearch reduce test runtime while maintaining correctness /ar-self-improve # uses nex-code's own benchmark as the fitness metric ``` ### Plan Mode Auto-activates for implementation tasks. Read-only analysis first, approve before writes. Hard-enforced tool r