@hanzo/helper

Sign in to Hanzo and use its AI models in Claude Code, Codex, and other coding tools.

One command points your coding tool at Hanzo Cloud: browser device login, an API key minted for you, and the tool configured to talk to api.hanzo.ai — which speaks both the OpenAI (/v1/chat/completions) and Anthropic (/v1/messages) protocols, so every model (Claude, GLM, GPT, DeepSeek, Kimi, …) works in tools built for either.

Quick start

npx @hanzo/helper login

That will:

1. Open hanzo.id and show you a device code to approve.
2. Mint (or reuse) your hk- Cloud API key.
3. Let you pick a default model.
4. Configure the coding tools you choose.

Then just run your tool — it's already talking to Hanzo:

claude          # Claude Code → Hanzo Cloud
codex           # Codex → Hanzo Cloud

Commands

Command	What it does
hanzo login	Device login, mint API key, configure tools
hanzo use [tool]	Point a tool at Hanzo using your saved key
hanzo unuse [tool]	Detach a tool from Hanzo (keep its other settings)
hanzo status	Session + every tool's configuration state
hanzo models	List models available to your key
hanzo auth status	Who you're signed in as
hanzo auth key [--reveal]	Show your current API key
hanzo auth rotate	Mint a fresh API key (old one stops working)
hanzo auth revoke	Revoke your API key
hanzo auth logout	Clear local credentials
hanzo models --tiers	Show the smart tiers (effort words → cloud aliases)
hanzo install [parts…]	Set up the ecosystem (dev, mcp, node, apps, …)
hanzo doctor	Diagnose connectivity and tool configuration

Smart tiers

The catalog is read live from api.hanzo.ai/v1/models — nothing is hardcoded. Beyond concrete ids (glm-5.2, deepseek-v4-pro, …) you can ask for an effort word and let the cloud pick the model:

Word	Routes to
auto	zen-auto	the cloud chooses (recommended default)
fast	zen-normal	quick, everyday
high	zen-pro	stronger reasoning & coding
max	zen-max	top tier (needs credits)
code	zen-code	coding-specialised
agent	zen-agent	agentic

hanzo use claude-code --model high      # or auto / fast / max / glm-5.2 …
hanzo models                            # full live catalog for your key

Supported coding tools

• Claude Code — adds a providers.hanzo block to ~/.claude/settings.json (additive; switch per-session with /model hanzo/<id>). Choose shell-env mode at login to make Hanzo the default for every Anthropic-compatible tool instead.
• Codex — adds a [model_providers.hanzo] provider to ~/.codex/config.toml (key in ~/.hanzo/env as HANZO_API_KEY).

The whole ecosystem

hanzo install              # interactive checklist (core tools pre-checked)
hanzo install dev mcp      # CLI agent + MCP server (npm)
hanzo install list         # everything available

Part	Kind
dev	npm	@hanzo/dev — CLI coding agent (code)
mcp	npm	@hanzo/mcp — MCP server (tools, browser, cloud)
node	guide	local inference node (bundles the engine)
desktop	guide	desktop app + the Enso browser
extension	guide	browser extension (Chrome / Firefox / Safari)
ide	guide	VS Code & JetBrains extensions
slack	guide	the Slack app
github	guide	the GitHub app

How it works

 hanzo login
     │
     ├── device login ─────────────▶ hanzo.id  (RFC 8628; proxies to iam.hanzo.ai)
     │     POST /oauth/device           → user_code + verification_uri
     │     POST /oauth/token  (poll)     → access_token
     │
     ├── mint API key ─────────────▶ iam  POST /v1/iam/mint-user-keys  → hk-…
     │     (self-authorized by your login token)
     │
     └── configure tools ──────────▶ ~/.claude/settings.json
                                     ~/.codex/config.toml
                                            │
 your coding tool ──────────────────▶ api.hanzo.ai
     OpenAI  /v1/chat/completions          (one key, every model)
     Anthropic /v1/messages

Self-hosted / white-label

Point the CLI at a different deployment with environment variables:

Var	Default	Purpose
HANZO_IAM_URL	https://hanzo.id	Identity / device login
HANZO_API_URL	https://api.hanzo.ai	Cloud API (keys, inference)
HANZO_CLIENT_ID	hanzo-app	OAuth client id (e.g. lux-app)

Configuration

~/.hanzo/config.json (mode 0600) holds your login token, API key, and identity. ~/.hanzo/env holds the raw key for tools that read it from the environment.

Build

pnpm install
pnpm build      # tsup → dist/
pnpm typecheck

License

Apache-2.0