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.

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.

Run /benchmark --discover to detect new models and auto-update this table.

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 — 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, auto-runs caffeinate on macOS:

nex-code -yolo

Headless / Programmatic:

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)

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

Commands

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

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 or Skills.

Key Features

Multi-Agent Orchestrator

Multi-goal prompts auto-decompose into parallel sub-agents (up to 5 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 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 restrictions during analysis phase.

Daemon / Watch Mode

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

Session Trees

Navigate conversation history like git branches — fork, switch, goto, delete branches without losing prior attempts.

Safety

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

Reporting vulnerabilities: Email security@schoensgibl.com — not a public issue. 72h initial response.

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

Visual Development Tools

Pixel-level before/after diffs, responsive sweeps (320–1920px), annotation overlays, design token extraction, and live-reload diff watching. Pure image tools work standalone; browser 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/.

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
  orchestrator.js        # Multi-agent decompose → execute → synthesize
  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 throughout
• SSRF protection on web_fetch
• MCP environment isolation

License

MIT