@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 kms pull	Pull env secrets from KMS for local dev (also kms)
hanzo install [parts…]	Set up the ecosystem (dev, mcp, node, apps, …)
hanzo doctor	Diagnose connectivity and tool configuration

Secrets for local dev (kms)

One login, one mechanism. Your hanzo login mints an IAM OIDC token; kms exchanges it for a short-lived KMS token and reads an environment's secrets. KMS owns secrets, envs and authz (/v1/kms/*); IAM only issues the token (/v1/iam/*) — they compose through the token, nothing braided.

kms pull --env devnet            # write .env for local dev (also: hanzo kms pull)
kms list --env devnet            # secret names only, no values
kms pull --env testnet --out -   # print to stdout

Environments: devnet (default), testnet, mainnet, production. CI uses the same /v1/kms/* exchange with a GitHub OIDC token — see .github/actions/kms-secrets and the reusable .github/workflows/npm-release.yml.

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