Hanzo Code

Hanzo Code is an open-source AI-native code editor -- a fork of VS Code (microsoft/vscode) with integrated LLM chat, autocomplete, inline diffs, and agent tool use baked directly into the editor co...

Overview

Hanzo Code is an open-source AI-native code editor -- a fork of VS Code (microsoft/vscode) with integrated LLM chat, autocomplete, inline diffs, and agent tool use baked directly into the editor core. It is the open-source Cursor alternative. The custom AI code lives in src/vs/workbench/contrib/code/browser/. Ships as a standalone Electron desktop app for macOS, Windows, and Linux.

Why Hanzo Code?

AI-native editor: Chat sidebar, Cmd+K inline edits, autocomplete, and agent mode built into the editor -- not an extension

Multi-provider LLM: Supports OpenAI, Anthropic, Google Gemini, Mistral, Groq, Ollama (local), and any OpenAI-compatible endpoint

Fast Apply: Search/Replace-based code application that works on 1000+ line files without rewriting the whole file

MCP tool use: Model Context Protocol integration for agent tool calling

Full VS Code compatibility: VS Code extensions, themes, settings, and keybindings all work

Tech Stack

Language: TypeScript (Electron app -- main + browser processes)

UI Framework: React 19 (bundled to browser process via custom build step)

Styling: Tailwind CSS 3 (scoped)

Build: Gulp + Webpack, npm scripts

Runtime: Electron 34, Node 20.18.x

LLM SDKs: @anthropic-ai/sdk, openai, @google/genai, @mistralai/mistralai, groq-sdk, ollama

MCP: @modelcontextprotocol/sdk ^1.11.2

Testing: Mocha (unit), Playwright (browser/e2e)

OSS Base

Fork of microsoft/vscode v1.94.0. Previously known as "Void Editor" -- references to void remain in internal code paths and product.json applicationName.

Repo: github.com/hanzoai/code

When to use

Building or contributing to the Hanzo Code editor

Adding new LLM providers or models

Extending the AI chat, autocomplete, or apply features

Creating new agent tools or MCP integrations within the editor

Packaging the editor for distribution

Hard requirements

Node.js 20.18.x (see .nvmrc)

npm (not pnpm -- this is a VS Code fork and uses npm workspaces)

Python and XCode (macOS) or Visual Studio 2022 (Windows) or build-essential (Linux) for native modules

Electron 34 (installed via devDependencies)

Quick reference

Item	Value
Website	`https://code.hanzo.ai`
Repo	`github.com/hanzoai/code`
Branch	`main`
License	MIT
Node Version	`20.18.2`
Package Manager	npm (not pnpm)
Editor Version	`1.94.0` (VS Code base)
Custom Code Path	`src/vs/workbench/contrib/code/browser/`
Data Folder	`~/.code-editor`
Bundle ID (macOS)	`com.hanzoai.code`
URL Protocol	`code-editor://`

One-file quickstart

Build and run from source

git clone https://github.com/hanzoai/code.git
cd code

# Install dependencies
npm install

# Build React UI components
npm run buildreact

# Watch-compile the editor (wait for two checkmarks)
npm run watch

# In another terminal, launch the editor
./scripts/code.sh          # macOS/Linux
# ./scripts/code.bat       # Windows

# Optional: isolate test data
./scripts/code.sh --user-data-dir ./.tmp/user-data --extensions-dir ./.tmp/extensions

Package for distribution

# macOS Apple Silicon
npm run gulp vscode-darwin-arm64

# macOS Intel
npm run gulp vscode-darwin-x64

# Windows
npm run gulp vscode-win32-x64

# Linux
npm run gulp vscode-linux-x64

Output folder appears as a sibling directory (e.g. ../VSCode-darwin-arm64/).

Core Concepts

Architecture

Code is an Electron app with two processes:

┌───────────────────────────────┐
│       Browser Process         │
│  (HTML/CSS/React UI)          │
│                               │
│  src/.../code/browser/        │
│  ├── react/          (React)  │
│  ├── chatThreadService        │
│  ├── autocompleteService      │
│  ├── editCodeService          │
│  ├── toolsService             │
│  ├── inlineDiffsService       │
│  └── sidebarPane              │
└──────────┬────────────────────┘
           │ IPC channels
┌──────────▼────────────────────┐
│       Main Process            │
│  (Node.js, node_modules)      │
│                               │
│  sendLLMMessage (all providers│
│  Anthropic, OpenAI, Gemini,   │
│  Mistral, Groq, Ollama)       │
└───────────────────────────────┘

browser/ code can use window and DOM but cannot import node_modules

electron-main/ code can import node_modules but has no DOM

common/ code is shared between both processes

LLM API calls run on electron-main to avoid CSP issues with local providers

Key Services

Service	File	Purpose
`chatThreadService`	67KB	Chat sidebar message handling, streaming, agent mode
`editCodeService`	89KB	Apply (Fast/Slow), Cmd+K, Edit tool -- all code modifications
`autocompleteService`	33KB	Inline completions from LLM
`inlineDiffsService`	64KB	Red/green diff rendering for pending changes
`toolsService`	24KB	Agent tool registration and execution
`terminalToolService`	14KB	Terminal command execution for agent
`voidSettingsService`	--	Provider/model configuration (implicit dependency for all AI services)
`contextGatheringService`	13KB	File and selection context for LLM prompts
`voidCommandBarService`	28KB	Command palette integration

Apply System

Two modes:

Fast Apply: LLM outputs <<<<<<< ORIGINAL / ======= / >>>>>>> UPDATED search/replace blocks. Works on large files.

Slow Apply: LLM rewrites the entire file content.

Key types:

DiffZone: A {startLine, endLine} region showing red/green diffs, with an optional llmCancelToken for streaming

DiffArea: Generalized line-number tracker

ModelSelection: {providerName, modelName} pair

ChatMode: normal | gather | agent

VS Code Internals

Editor: The Monaco editor instance (one per split pane, tabs share it)

Model (ITextModel): Internal file content representation, shared across editors

URI: File path identifier for models

Service: Singleton class registered with registerSingleton, injected via @IServiceName decorator

Action/Command: Registered functions callable from command palette (Cmd+Shift+P) or by ID

Directory structure

code/
├── src/vs/workbench/contrib/code/browser/   # ALL custom Hanzo Code AI features
│   ├── react/                    # React UI (chat sidebar, settings)
│   ├── helpers/                  # Shared utility functions
│   ├── helperServices/           # Small helper singleton services
│   ├── prompt/                   # LLM prompt templates
│   ├── media/                    # CSS and assets
│   ├── chatThreadService.ts      # Chat + agent orchestration
│   ├── editCodeService.ts        # Apply, Cmd+K, Edit tool
│   ├── autocompleteService.ts    # Inline completions
│   ├── inlineDiffsService.ts     # Diff visualization
│   ├── toolsService.ts           # Agent tool system
│   └── ...                       # 35+ service files
├── src/vs/                       # VS Code core (mostly untouched)
├── extensions/                   # Built-in VS Code extensions
├── build/                        # Build scripts (Gulp tasks)
├── cli/                          # CLI tool
├── remote/                       # Remote development server
├── test/                         # Test infrastructure
├── product.json                  # Editor identity and branding
├── package.json                  # npm deps (v1.94.0)
└── .nvmrc                        # Node 20.18.2

Troubleshooting

Issue	Cause	Solution
Build fails with native module errors	Wrong Node version	Use Node 20.18.x (check `.nvmrc`)
`TypeError: Failed to fetch dynamically imported module`	Missing `.js` extension in imports	Ensure all TS imports end with `.js`
Missing styles after build	CSS not yet compiled	Wait a few seconds, then Cmd+R to reload
React UI not rendering	React not built	Run `npm run buildreact` before watch
CSP errors with local LLM	Provider called from browser process	LLM calls must go through electron-main IPC
Extensions gallery empty	Missing `extensionsGallery` in product.json	Already configured for VS Marketplace

Development rules (from .voidrules)

Never modify files outside src/vs/workbench/contrib/code/ without consulting first

Never lazily cast to any -- find the correct type

Do not add or remove semicolons -- follow existing convention

Type naming: bOfA pattern (e.g. toolNameOfToolId for a map from tool ID to name)

hanzo/hanzo-extension.md - VS Code / browser extension (separate repo, not the editor itself)

hanzo/hanzo-aci.md - Agent Computer Interface (Python backend for agent tools)

hanzo/hanzo-mcp.md - Model Context Protocol tools

hanzo/hanzo-llm-gateway.md - LLM proxy (api.hanzo.ai)

On this page