ai-development-guide

This guide covers setting up Hanzo's full AI development stack — extensions, CLI agents, MCP tools, Zen models, and skills for cross-stack work across Hanzo AI and Lux blockchain.

How to Use AI with Hanzo and Lux

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

Overview

This guide covers setting up Hanzo's full AI development stack — extensions, CLI agents, MCP tools, Zen models, and skills for cross-stack work across Hanzo AI and Lux blockchain.

1. Install Hanzo Extension (All Platforms)

The Hanzo extension provides AI chat, code completion, and MCP tool access across all browsers and IDEs. Everything ships from a single monorepo (github.com/hanzoai/extension v1.8.0).

Browser Extensions

| Browser | Install | |---------|---------| | Chrome | Chrome Web Store — search "Hanzo" | | Firefox | Firefox AMO — search "Hanzo" | | Safari | Available via macOS App Store |

IDE Extensions

| IDE | Install | |-----|---------| | VS Code / Cursor | Marketplace → search @hanzo/extension | | Open VSX (VSCodium) | Open VSX Registry → search "Hanzo" | | JetBrains | JetBrains Marketplace → search "Hanzo" |

What You Get

AI chat sidebar in browser and IDE
Code completion with Zen models
MCP tool access (13 unified tools)
Auth via hanzo.id (@hanzo/iam, OAuth2 + PKCE)
Access to 435 models (28 Zen + 400+ third-party) via api.hanzo.ai/v1/chat/completions

Configuration

After installing, sign in via hanzo.id. The extension authenticates using the @hanzo/iam SDK (OAuth2 authorization-code + PKCE S256) — no API key management needed. LLM requests route through api.hanzo.ai/v1/chat/completions.

2. Hanzo Dev for CLI Coding

Hanzo Dev is a terminal-based AI coding agent for agentic development workflows.

Install

# Via npm
npm install -g @hanzo/dev

# Or run directly
npx @hanzo/dev

Usage

# Interactive chat mode
hanzo-dev chat

# Non-interactive task mode
hanzo-dev task "Add authentication middleware to the Express API"

# With specific Zen model
hanzo-dev --model zen-70b chat

# With MCP tool servers
hanzo-dev --mcp hanzo-node,hanzo-ui chat

Key Commands

| Command | Purpose | |---------|---------| | /plan | Create implementation plan | | /code | Generate code | | /solve | Debug and fix issues | | /auto | Autonomous mode | | /browser | Browser automation |

3. MCP vs ZAP — Choosing Your Protocol

Two protocols for connecting AI agents to tools:

Hanzo MCP (`@hanzo/mcp` v2.4.1)

Standard Model Context Protocol. Works with Claude Code, Cursor, and any MCP-compatible client.

# Install globally
npm install -g @hanzo/mcp

# Add to Claude Code
claude mcp add hanzo-mcp -- hanzo-mcp serve

# List available tools
hanzo-mcp list-tools

13 HIP-0300 unified tools — action-routed, so each tool handles multiple operations.

Best for: Claude Code, Cursor, any standard MCP client.

ZAP (Zero-copy Agent Protocol)

Hanzo's native protocol. Uses significantly less memory than MCP because it avoids JSON serialization overhead — direct memory-mapped communication.

# Use ZAP when running hanzo-dev natively
hanzo-dev --protocol zap chat

Best for: Hanzo Dev native mode, intensive workflows, memory-constrained environments.

When to Use Which

| Scenario | Recommendation | |----------|---------------| | Claude Code | MCP (only option) | | Cursor IDE | MCP | | Hanzo Dev (native) | ZAP (less memory, faster) | | Heavy multi-agent workflows | ZAP | | Third-party MCP clients | MCP |

4. Zen AI — Hanzo's Frontier Models

Zen is Hanzo's frontier model family built on MoDE (Mixture of Diverse Experts) architecture. Available from 600M to 480B parameters.

Available Models

28 Zen models accessible via the LLM gateway at api.hanzo.ai/v1. Use in any OpenAI-compatible client:

from openai import OpenAI

client = OpenAI(
 base_url="https://api.hanzo.ai/v1",
 api_key="your-hanzo-api-key"
)

response = client.chat.completions.create(
 model="zen-70b",
 messages=[{"role": "user", "content": "Explain post-quantum cryptography"}]
)

Local Inference

Run Zen models locally via Hanzo Engine or Hanzo Node:

# Via Hanzo Node (AI agent node)
hanzo-node start --model zen-8b

# Or via the engine directly
hanzo-engine serve --model zen-8b --port 8080

Using with Hanzo Dev

# Use Zen models natively
hanzo-dev --model zen-70b chat

# Auto-route (picks best model for task)
hanzo-dev --auto-route chat

5. Install Skills for Cross-Stack Development

Skills provide progressive disclosure of Hanzo and Lux documentation — AI agents load only what they need, when they need it.

Install Hanzo Skills (49 skills)

git clone https://github.com/hanzoai/skills.git

Covers: AI infrastructure, cloud services, platform, SDKs (Python/JS/Go/Rust), identity, security, developer tools, ML, data, observability.

Install Lux Skills (31 skills)

git clone https://github.com/luxfi/skills.git

Covers: blockchain node, Quasar consensus, EVM, DEX (CLOB), exchange (AMM), cryptography (BLS/FHE/lattice), wallet, bridge, monitoring, governance.

Configure in Claude Code

Add to your project's CLAUDE.md:

## Skills

Load Hanzo skills for AI infrastructure context:
cat path/to/hanzo/skills/skills/hanzo/INDEX.md

Load Lux skills for blockchain context:
cat path/to/lux/skills/skills/lux/INDEX.md

Progressive Disclosure

Tier 1: Gateway (auto-discovers relevant skills)
 → hanzo/SKILL.md

Tier 2: INDEX (full catalog with decision tree)
 → skills/hanzo/INDEX.md or skills/lux/INDEX.md

Tier 3: Individual skills (deep technical detail)
 → skills/hanzo/hanzo-mcp.md, skills/lux/lux-consensus.md, etc.

6. Cross-Stack Workflow Examples

Example 1: AI-Powered DeFi Dashboard

Skills needed:
 Hanzo: hanzo-chat.md, hanzo-ui.md, python-sdk.md
 Lux: lux-exchange.md, lux-dex.md, lux-evm.md

Flow:
1. Use Zen model to analyze market data (python-sdk)
2. Query Lux DEX CLOB for order book (lux-dex API)
3. Display in Hanzo UI components (hanzo-ui)
4. Deploy to Hanzo Platform (hanzo-platform)

Example 2: Privacy-First Blockchain Analytics

Skills needed:
 Hanzo: hanzo-search.md, hanzo-engine.md
 Lux: lux-explorer.md, lux-fhe.md, lux-evm.md

Flow:
1. Index blockchain data with Hanzo Search (Meilisearch, Rust)
2. Run analytics on encrypted data via Lux FHE
3. Serve results via local inference (hanzo-engine)
4. Query via Lux Explorer (Blockscout)

Example 3: Multi-Agent Trading Bot

Skills needed:
 Hanzo: hanzo-agent.md, hanzo-mcp.md, hanzo-kms.md
 Lux: lux-dex.md, lux-bridge.md, lux-oracle.md

Flow:
1. Agent monitors oracle prices (lux-oracle)
2. Routes orders to CLOB engine (lux-dex, 434M orders/sec)
3. Cross-chain settlement via bridge (lux-bridge, MPC)
4. API keys secured in KMS (hanzo-kms, 8 Vault subsystems)

7. Quick Start Checklist

Sign up at hanzo.ai for API key
Install browser extension (Chrome/Firefox/Safari)
Install IDE extension (VS Code/JetBrains)
Install Hanzo Dev CLI: npm install -g @hanzo/dev
Install MCP tools: npm install -g @hanzo/mcp
Clone Hanzo skills: git clone https://github.com/hanzoai/skills.git
Clone Lux skills: git clone https://github.com/luxfi/skills.git
Configure Claude Code (if using): add MCP server via claude mcp add
Try a Zen model: hanzo-dev --model zen-70b chat
Explore skills: cat skills/hanzo/INDEX.md or cat skills/lux/INDEX.md

Key Endpoints

| Service | URL | |---------|-----| | LLM API | api.hanzo.ai/v1/chat/completions | | Auth | hanzo.id | | Chat UI | chat.hanzo.ai | | Cloud | cloud.hanzo.ai | | Console | console.hanzo.ai | | KMS | kms.hanzo.ai | | Platform | platform.hanzo.ai | | Search | search.hanzo.ai | | Studio | studio.hanzo.ai | | Lux Gateway | api.lux.network | | Lux Explorer | explorer.lux.network | | Lux Monitor | monitor.lux.network |

Last Updated: 2026-03-13 Category: Hanzo Ecosystem Related: getting-started, setup, ai, development Prerequisites: Node.js 18+, npm/pnpm