Hanzo Code

Overview

Hanzo Code is an open-source AI-native code editor. LLM chat, autocomplete, inline diffs and agent tool use live in the editor core rather than in an extension, which is what lets the model see and edit across the whole workspace instead of one buffer at a time. The AI code lives in src/vs/workbench/contrib/code/browser/. Full extension, theme and keybinding compatibility with the VS Code ecosystem. 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)

Repo

github.com/hanzoai/code. Package code-dev v1.94.0.

Note for contributors: internal code paths and product.json's applicationName still read void. Those are load-bearing identifiers — the data folder and bundle id derive from them — so do not rename them casually.

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 -- the workspace layout is npm's)
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

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

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

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)

Related Skills

• 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-ai-api.md - the Hanzo AI API (api.hanzo.ai)