Files

9.2 KiB

Hanzo Code - Open-Source AI Code Editor

Category: Hanzo Ecosystem Related Skills: hanzo/hanzo-extension.md, hanzo/hanzo-mcp.md, hanzo/hanzo-aci.md

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

  1. Node.js 20.18.x (see .nvmrc)
  2. npm (not pnpm -- this is a VS Code fork and uses npm workspaces)
  3. Python and XCode (macOS) or Visual Studio 2022 (Windows) or build-essential (Linux) for native modules
  4. 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)

Last Updated: 2026-03-13 Category: Hanzo Ecosystem Related: editor, vscode, ai, llm, cursor-alternative Prerequisites: Node.js 20, npm, platform build tools (XCode/VS/gcc)