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

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 — the flat-rate platform running devstral, Kimi K2, Qwen3-Coder, and 47+ models. Other providers (OpenAI, Anthropic, Gemini) work via the same interface.

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. See Tools for the full list.

=======

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. See Tools for the full list.

Stashed changes 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.

Rankings are nex-code-specific: tool name accuracy, argument validity, schema compliance. Toolathon (Minimax SOTA) measures different task types — run /benchmark --discover after model releases.

Recommended .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).

# .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 — enables grounded web search

DEFAULT_PROVIDER=ollama
DEFAULT_MODEL=devstral-2:123b

Install from source:

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 — file changes, dangerous commands, and tool permissions are auto-approved. Auto-runs caffeinate on macOS.

nex-code -yolo

Headless / Programmatic Mode

nex-code --task "refactor src/index.js to async/await" --yolo
nex-code --prompt-file /tmp/task.txt --yolo --json
nex-code --daemon          # watch mode: fires tasks on file changes, git commits, or cron

Vision / Screenshot

=======

Vision / Screenshot

Stashed changes

> /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 capture
> screenshot localhost:3000 and review the navbar spacing

Works with Anthropic, OpenAI, Gemini, and Ollama vision models. Formats: PNG, JPG, GIF, WebP, BMP.

Providers & Models

/model                         # interactive picker
/model openai:gpt-4o           # switch directly
/providers                     # list all
/fallback anthropic,openai     # auto-switch on failure

Commands

Type / to see inline suggestions. Tab completion for slash commands and file paths.

Tools

45 built-in tools organized by category:

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, framework stack before any frontend work

Visual: visual_diff, responsive_sweep, visual_annotate, visual_watch, design_tokens, design_compare

Additional tools via MCP servers or Skills.

Key Features

Multi-Agent Orchestrator

Multi-goal prompts auto-decompose into parallel sub-agents. Up to 5 agents run simultaneously with file locking.

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 branch.

/autoresearch reduce test runtime while maintaining correctness
/ar-self-improve          # self-improvement using nex-code's benchmark

Plan Mode

Auto-activates for implementation tasks. Read-only analysis first, approve before writes. Hard-enforced tool restrictions.

Daemon / Watch Mode

<<<<<<< Updated upstream Background process that fires tasks on file changes, git commits, or cron schedule. Configured via .nex/daemon.json. Desktop and Matrix notifications.

Background process that fires tasks on file changes, git commits, or cron schedule. Configured via .nex/daemon.json. Desktop and Matrix notifications.

Stashed changes

Session Trees

Navigate conversation history like git branches — fork, switch, goto, delete branches.

Safety

Pre-push secret detection, audit logging (JSONL), persistent undo/redo, cost limits, auto plan mode.

Open-Source Model Robustness

• 5-layer argument parsing — JSON, trailing fix, extraction, key repair, fence stripping
• Tool call retry with schema hints — malformed args get the expected schema for self-correction
• Auto-fix engine — path resolution, edit fuzzy matching (Levenshtein), bash error hints
• Tool tiers — essential (5) / standard (21) / full (45), auto-selected per model capability
• Stale stream recovery — progressive retry with context compression on stall <<<<<<< Updated upstream

Visual Development Tools

Pixel-level before/after comparison, responsive sweeps (320-1920px), annotation overlays, design token extraction, and live-reload diff watching. Pure image tools work standalone; browser-based tools need Playwright.

Extensibility

Skills

Drop .md or .js files in .nex/skills/ for project-specific knowledge, commands, and tools. Global skills in ~/.nex-code/skills/. Install from git: /install-skill user/repo.

Plugins

Custom tools and lifecycle hooks via .nex/plugins/. Events: onToolResult, onModelResponse, onSessionStart, onSessionEnd, onFileChange, beforeToolExec, afterToolExec.

MCP

Connect external tool servers via Model Context Protocol. Configure in .nex/mcp.json with env var interpolation.

Hooks

Run custom scripts on CLI events (pre-tool, post-tool, pre-commit, post-response, session-start, session-end). Configure in .nex/config.json or .nex/hooks/.

=======

Visual Development Tools

Pixel-level before/after comparison, responsive sweeps (320-1920px), annotation overlays, design token extraction, and live-reload diff watching. Pure image tools work standalone; browser-based tools need Playwright.

Extensibility

Skills

Drop .md or .js files in .nex/skills/ for project-specific knowledge, commands, and tools. Global skills in ~/.nex-code/skills/. Install from git: /install-skill user/repo.

Plugins

Custom tools and lifecycle hooks via .nex/plugins/. Events: onToolResult, onModelResponse, onSessionStart, onSessionEnd, onFileChange, beforeToolExec, afterToolExec.

MCP

Connect external tool servers via Model Context Protocol. Configure in .nex/mcp.json with env var interpolation.

Hooks

Run custom scripts on CLI events (pre-tool, post-tool, pre-commit, post-response, session-start, session-end). Configure in .nex/config.json or .nex/hooks/.

Stashed changes

VS Code Extension

Built-in sidebar chat panel (vscode/) with streaming output, collapsible tool cards, and native theme support. Spawns nex-code --server over JSON-lines IPC.

cd vscode && npm install && npm run package
# Cmd+Shift+P -> Extensions: Install from VSIX...

Architecture

bin/nex-code.js          # Entrypoint
cli/
  agent.js               # Agentic loop + conversation state + guards
  providers/             # Ollama, OpenAI, Anthropic, Gemini, Local + wire protocols
  tools/index.js         # 45 tool definitions + auto-fix engine
  context-engine.js      # Token management + 5-phase compression
  sub-agent.js           # Parallel sub-agents with file locking
<<<<<<< Updated upstream
orchestrator.js        # Multi-agent decompose -> execute -> synthesize
=======
  orchestrator.js        # Multi-agent decompose -> execute -> synthesize
>>>>>>> Stashed changes
  session-tree.js        # Session branching
  visual.js              # Visual dev tools (pixelmatch-based)
  browser.js             # Playwright browser agent
  skills/                # Built-in + user skills

See DEVELOPMENT.md for full architecture details.

Testing

npm test              # 97 suites, 3920 tests
npm run typecheck     # TypeScript noEmit check
npm run benchmark:gate        # 7-task smoke test (blocks push on regression)
npm run benchmark:reallife    # 35 real-world tasks across 7 categories

Security

• Pre-push secret detection (API keys, private keys, hardcoded credentials)
• Audit logging with automatic argument sanitization
• Sensitive path blocking (.ssh/, .aws/, .env, credentials)
• Shell injection protection via execFileSync with argument arrays
• SSRF protection on web_fetch
• MCP environment isolation

Reporting vulnerabilities: Email security@schoensgibl.com (not a public issue). Allow 72h for initial response.

License

MIT