mirror of
https://github.com/hanzo-docs/docs.git
synced 2026-10-24 20:09:02 +00:00
Coding tools: desktop apps and editors, the add-once toolset, Windows, measured speed
Hanzo CI/CD / test (linux-amd64) (push) Skipped
Hanzo CI/CD / test (linux-arm64) (push) Skipped
Hanzo CI/CD / test-advisory (push) Skipped
Hanzo CI/CD / cicd (push) Failing after 5m19s
Hanzo CI/CD / test-amd64 (push) Successful in 15m52s
CI/CD / cicd (push) Failing after 21m16s
Hanzo CI/CD / test (linux-amd64) (push) Skipped
Hanzo CI/CD / test (linux-arm64) (push) Skipped
Hanzo CI/CD / test-advisory (push) Skipped
Hanzo CI/CD / cicd (push) Failing after 5m19s
Hanzo CI/CD / test-amd64 (push) Successful in 15m52s
CI/CD / cicd (push) Failing after 21m16s
A page for Claude Desktop, Cursor, VS Code, Windsurf, Zed, JetBrains and the Codex, Claude Code and Continue apps: hanzo-mcp as an MCP server, and the app's own model on api.hanzo.ai with an OpenAI- or Anthropic- compatible setting. Cursor, Grok, Antigravity and Gemini take the toolset once in their own configuration. Windows installs through npm and `hanzo upgrade`. The coding page states the measured runs, each linked. Claude-Session: https://claude.ai/code/session_01M8RoubcPN71KgJuZ8LdBUL
This commit is contained in:
@@ -14,7 +14,7 @@ hanzo upgrade gemini
|
||||
hanzo --gemini "explain the build"
|
||||
```
|
||||
|
||||
- **Toolset:** a settings file for the run, named by `GEMINI_CLI_SYSTEM_SETTINGS_PATH`.
|
||||
- **Toolset:** added once, `gemini mcp add -s user hanzo ~/.local/bin/hanzo-mcp`. Gemini CLI reads a run's settings file only when root owns it, so `hanzo` cannot hand it one, and it loads MCP servers only in folders you have trusted.
|
||||
- **Acts without asking:** `--yolo`. `--ask` leaves its prompts.
|
||||
- **Models:** your Google account or `GEMINI_API_KEY`. Gemini CLI speaks only Google's API, so `--cloud` does not apply.
|
||||
|
||||
@@ -97,10 +97,10 @@ curl -fsSL https://x.ai/cli/install.sh | bash
|
||||
hanzo --grok "draft the migration"
|
||||
```
|
||||
|
||||
xAI's Grok Build. It installs `grok`, and also a binary named `agent`; `hanzo --cursor` therefore runs `cursor-agent` first, so the two never trade places.
|
||||
xAI's Grok Build. Its installer also links a binary named `agent`, to Grok, as Cursor's does to Cursor. `hanzo --cursor` runs `cursor-agent` and never a bare `agent`, so the two never trade places. To keep `agent` meaning Cursor in your shell, leave `~/.grok/bin` off your PATH and link only `grok`: `ln -sfn ~/.grok/bin/grok ~/.local/bin/grok`.
|
||||
|
||||
- **Acts without asking:** `--always-approve`. Headless runs use `-p`.
|
||||
- **Toolset:** Grok Build reads servers only from its saved configuration (`grok mcp add`), so the toolset is not attached for one run.
|
||||
- **Toolset:** added once, `grok mcp add --scope user hanzo ~/.local/bin/hanzo-mcp`. Grok Build reads servers only from its saved configuration.
|
||||
- **Models:** your xAI account (`grok login` or `XAI_API_KEY`). `--cloud` does not apply.
|
||||
|
||||
## Goose
|
||||
|
||||
@@ -26,7 +26,7 @@ Antigravity keeps its own login and its own backend. `hanzo --agy` has no gatewa
|
||||
|
||||
- **No routing.** Antigravity's model calls do not go through api.hanzo.ai, and Hanzo does not see them.
|
||||
- **No metering.** Nothing is counted into your org's usage. The end-of-session block prints the duration and the session link, and says Antigravity ran on its own account.
|
||||
- **No Hanzo toolset.** Antigravity takes no MCP server for a single run, so the Hanzo toolset is not attached, and the summary says so.
|
||||
- **No Hanzo toolset for one run.** Antigravity takes no MCP server for a single run, and the summary says so. Add it once and every run loads it: `agy mcp add hanzo ~/.local/bin/hanzo-mcp`.
|
||||
- **No resume.** The tool discloses no session id to the wrapper, so `hanzo --resume` has nothing to continue.
|
||||
|
||||
## See the session
|
||||
|
||||
@@ -11,7 +11,7 @@ hanzo login
|
||||
hanzo --cursor
|
||||
```
|
||||
|
||||
This runs Cursor's agent CLI, `agent`, or `cursor-agent` where that is the only name on your path. Install and sign in to it first, as you would to use it alone. `agent` and `cursor-agent` are accepted spellings of `cursor`.
|
||||
This runs Cursor's agent CLI as `cursor-agent`, never a bare `agent`: xAI's Grok installer links an `agent` of its own. Install and sign in to it first, as you would to use it alone. `agent` and `cursor-agent` are accepted spellings of `cursor`.
|
||||
|
||||
## What the wrapper does
|
||||
|
||||
@@ -26,7 +26,7 @@ Cursor keeps its own login and its own backend. `hanzo --cursor` has no gateway
|
||||
|
||||
- **No routing.** Cursor's model calls do not go through api.hanzo.ai, and Hanzo does not see them.
|
||||
- **No metering.** Nothing is counted into your org's usage. The end-of-session block prints the duration and the session link, and says Cursor ran on its own account.
|
||||
- **No Hanzo toolset.** Cursor takes no MCP server for a single run, so the Hanzo toolset is not attached, and the summary says so.
|
||||
- **No Hanzo toolset for one run.** Cursor takes no MCP server for a single run, and the summary says so. Add it once to `~/.cursor/mcp.json` and the editor and `cursor-agent` both load it: [Desktop apps and editors](/docs/guides/coding/desktop).
|
||||
- **No resume.** The tool discloses no session id to the wrapper, so `hanzo --resume` has nothing to continue.
|
||||
|
||||
## See the session
|
||||
|
||||
@@ -0,0 +1,129 @@
|
||||
---
|
||||
title: Desktop apps and editors
|
||||
description: "Give Claude Desktop, Cursor, VS Code, Windsurf, Zed, JetBrains and the Codex and Claude Code apps the Hanzo toolset, and run their models on your Hanzo plan."
|
||||
---
|
||||
|
||||
An app reaches Hanzo two ways, apart or together:
|
||||
|
||||
- **The toolset.** Add `hanzo-mcp` as an MCP server. The app's own model keeps its own plan and hands work to Enso and Kai through the tools, as an agent does under `hanzo --<agent>`.
|
||||
- **Its model.** Point the app's OpenAI- or Anthropic-compatible model setting at `api.hanzo.ai`. Its model calls then run on your Hanzo plan.
|
||||
|
||||
## Install and sign in once
|
||||
|
||||
```bash
|
||||
curl -fsSL hanzo.sh | sh # macOS and Linux: hanzo, hanzo-mcp, dev, zt
|
||||
npm install -g @hanzo/cli && hanzo upgrade # Windows: hanzo, then hanzo-mcp, dev and zt beside it
|
||||
hanzo login
|
||||
```
|
||||
|
||||
With no key set, `hanzo-mcp` (1.1.33 and later) uses that sign-in, so an app can start it with no environment of its own.
|
||||
|
||||
## The toolset in any MCP app
|
||||
|
||||
Most apps take the same entry:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"hanzo": { "command": "/Users/you/.local/bin/hanzo-mcp" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Write the full path. An app started from the Dock, the Start menu or a launcher does not read your shell's PATH. `which hanzo-mcp` prints it; on Windows, `where hanzo-mcp`.
|
||||
|
||||
| App | Where the entry goes |
|
||||
| --- | --- |
|
||||
| Claude Desktop | Settings → Developer → Edit Config (`claude_desktop_config.json`) |
|
||||
| Cursor, editor and `cursor-agent` | `~/.cursor/mcp.json` |
|
||||
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
|
||||
| Cline, Roo Code, Kilo Code | the extension's MCP Servers panel → Configure |
|
||||
| VS Code agent mode | `.vscode/mcp.json`, as `{"servers": {"hanzo": {"type": "stdio", "command": "…/hanzo-mcp"}}}` |
|
||||
| Claude Code, terminal and IDE extensions | `claude mcp add --scope user hanzo -- /Users/you/.local/bin/hanzo-mcp` |
|
||||
| Codex, app, IDE extension and CLI | `~/.codex/config.toml`, as below |
|
||||
| Grok Build | `grok mcp add --scope user hanzo /Users/you/.local/bin/hanzo-mcp` |
|
||||
| Zed, JetBrains AI Assistant | their MCP settings, with the same command |
|
||||
|
||||
Then ask for the work by name: "use kai_decide to sort these 200 tickets by queue", "have llm summarise this log".
|
||||
|
||||
## The app's model on Hanzo
|
||||
|
||||
An OpenAI-compatible model setting takes three values:
|
||||
|
||||
- **Base URL:** `https://api.hanzo.ai/v1`
|
||||
- **API key:** a secret key (`sk-…`) from [console.hanzo.ai/api-keys](https://console.hanzo.ai/api-keys)
|
||||
- **Model:** `enso-auto`, which picks a model per request within your plan, or any id from `GET https://api.hanzo.ai/v1/models`
|
||||
|
||||
An Anthropic-compatible setting takes `https://api.hanzo.ai` as its base and the same key.
|
||||
|
||||
| App | Setting |
|
||||
| --- | --- |
|
||||
| Cursor | Settings → Models: OpenAI API Key, Override OpenAI Base URL, then add `enso-auto` as a model |
|
||||
| Cline, Roo Code, Kilo Code | API Provider: OpenAI Compatible, with the base URL, key and model ID |
|
||||
| Continue | `config.yaml`, as below |
|
||||
| Zed | `language_models.openai_compatible` in `settings.json` |
|
||||
| JetBrains AI Assistant | its OpenAI-compatible provider, with the base URL and key |
|
||||
| Claude Desktop | none: it runs Anthropic's models only. Add the toolset. |
|
||||
|
||||
### Claude Code, in the terminal and the IDE extensions
|
||||
|
||||
The extensions read the same `~/.claude/settings.json` as the CLI:
|
||||
|
||||
```json
|
||||
{
|
||||
"apiKeyHelper": "/Users/you/.local/bin/hanzo auth token",
|
||||
"env": {
|
||||
"ANTHROPIC_BASE_URL": "https://api.hanzo.ai",
|
||||
"ANTHROPIC_MODEL": "enso",
|
||||
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "enso"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The helper prints your sign-in's current token, so no key is written into the file. In a terminal, `hanzo --claude --cloud` does the same for one run and edits nothing.
|
||||
|
||||
### Codex, in the app, the IDE extension and the CLI
|
||||
|
||||
All three read `~/.codex/config.toml`:
|
||||
|
||||
```toml
|
||||
model_provider = "hanzo"
|
||||
model = "enso-auto"
|
||||
|
||||
[model_providers.hanzo]
|
||||
name = "Hanzo"
|
||||
base_url = "https://api.hanzo.ai/v1"
|
||||
wire_api = "responses"
|
||||
|
||||
[model_providers.hanzo.auth]
|
||||
command = "/Users/you/.local/bin/hanzo"
|
||||
args = ["auth", "token"]
|
||||
refresh_interval_ms = 600000
|
||||
|
||||
[mcp_servers.hanzo]
|
||||
command = "/Users/you/.local/bin/hanzo-mcp"
|
||||
```
|
||||
|
||||
### Continue, in VS Code, JetBrains and `cn`
|
||||
|
||||
`~/.continue/config.yaml`, with the key in the `HANZO_API_KEY` environment variable or Continue's secrets:
|
||||
|
||||
```yaml
|
||||
name: Hanzo
|
||||
version: 1.0.0
|
||||
schema: v1
|
||||
models:
|
||||
- name: Enso
|
||||
provider: openai
|
||||
model: enso-auto
|
||||
apiBase: https://api.hanzo.ai/v1
|
||||
apiKey: ${{ secrets.HANZO_API_KEY }}
|
||||
roles: [chat, edit, apply]
|
||||
mcpServers:
|
||||
- name: hanzo
|
||||
command: /Users/you/.local/bin/hanzo-mcp
|
||||
```
|
||||
|
||||
## What it used
|
||||
|
||||
Calls on your key or sign-in show in `hanzo usage summary --range 7d`, `hanzo console` (press `6`) and [platform.hanzo.ai](https://platform.hanzo.ai). The per-session block that `hanzo --<agent>` prints is a terminal feature; an app's own sessions are not summarised there.
|
||||
@@ -26,9 +26,9 @@ hanzo --claude "fix the failing test in api/users" # one quoted task runs head
|
||||
| Hanzo Dev | `hanzo` or `hanzo dev` | hanzo.sh | yes | always on Hanzo |
|
||||
| [Claude Code](/docs/guides/coding/claude-code) | `hanzo --claude` | Anthropic | yes | yes |
|
||||
| [Codex](/docs/guides/coding/codex) | `hanzo --codex` | OpenAI | yes | yes |
|
||||
| [Cursor](/docs/guides/coding/cursor) | `hanzo --cursor` | Cursor | no | no |
|
||||
| [Antigravity](/docs/guides/coding/antigravity) | `hanzo --agy` | Google | no | no |
|
||||
| [Gemini CLI](/docs/guides/coding/agents#gemini-cli) | `hanzo --gemini` | `hanzo upgrade gemini` | yes | no |
|
||||
| [Cursor](/docs/guides/coding/cursor) | `hanzo --cursor` | Cursor | added once | no |
|
||||
| [Antigravity](/docs/guides/coding/antigravity) | `hanzo --agy` | Google | added once | no |
|
||||
| [Gemini CLI](/docs/guides/coding/agents#gemini-cli) | `hanzo --gemini` | `hanzo upgrade gemini` | added once | no |
|
||||
| [Qwen Code](/docs/guides/coding/agents#qwen-code) | `hanzo --qwen` | `hanzo upgrade qwen` | yes | yes |
|
||||
| [OpenCode](/docs/guides/coding/agents#opencode) | `hanzo --opencode` | `hanzo upgrade opencode` | yes | yes |
|
||||
| [Kilo Code](/docs/guides/coding/agents#kilo-code) | `hanzo --kilo` | `hanzo upgrade kilo` | yes | yes |
|
||||
@@ -36,7 +36,7 @@ hanzo --claude "fix the failing test in api/users" # one quoted task runs head
|
||||
| [Pi](/docs/guides/coding/agents#pi) | `hanzo --pi` | `hanzo upgrade pi` | no | yes |
|
||||
| [GitHub Copilot CLI](/docs/guides/coding/agents#github-copilot-cli) | `hanzo --copilot` | `hanzo upgrade copilot` | yes | no |
|
||||
| [Amp](/docs/guides/coding/agents#amp) | `hanzo --amp` | `hanzo upgrade amp` | yes | no |
|
||||
| [Grok Build](/docs/guides/coding/agents#grok-build) | `hanzo --grok` | xAI's installer | no | no |
|
||||
| [Grok Build](/docs/guides/coding/agents#grok-build) | `hanzo --grok` | xAI's installer | added once | no |
|
||||
| [Goose](/docs/guides/coding/agents#goose) | `hanzo --goose` | Goose's installer | yes | yes |
|
||||
| [Aider](/docs/guides/coding/agents#aider) | `hanzo --aider` | `uv tool install aider-chat` | no | yes |
|
||||
| [Hermes Agent](/docs/guides/coding/agents#hermes-agent) | `hanzo --hermes` | Nous Research's installer | with `--cloud` | yes |
|
||||
@@ -49,7 +49,7 @@ hanzo --claude "fix the failing test in api/users" # one quoted task runs head
|
||||
| [Letta Code](/docs/guides/coding/agents#letta-code) | `hanzo --letta` | `hanzo upgrade letta` | no | no |
|
||||
| [Kode](/docs/guides/coding/agents#kode) | `hanzo --kode` | `hanzo upgrade kode` | yes | no |
|
||||
|
||||
Each agent is also `hanzo dev --<agent>` and `hanzo dev --backend <agent>`, and `hanzo code` is `hanzo dev`. `hanzo upgrade <agent>` installs an npm-shipped agent under `~/.hanzo`, where `hanzo` finds it without changing your PATH. Make one agent the default for a bare `hanzo` with `agent` in `~/.hanzo/settings.json`.
|
||||
"Added once" means the agent takes no MCP server for a single run, so you add `hanzo-mcp` to its own configuration one time: `gemini mcp add -s user hanzo ~/.local/bin/hanzo-mcp`, `grok mcp add --scope user hanzo ~/.local/bin/hanzo-mcp`, `agy mcp add hanzo ~/.local/bin/hanzo-mcp`, or Cursor's `~/.cursor/mcp.json` ([Desktop apps and editors](/docs/guides/coding/desktop)). Each agent is also `hanzo dev --<agent>` and `hanzo dev --backend <agent>`, and `hanzo code` is `hanzo dev`. `hanzo upgrade <agent>` installs an npm-shipped agent under `~/.hanzo`, where `hanzo` finds it without changing your PATH. Make one agent the default for a bare `hanzo` with `agent` in `~/.hanzo/settings.json`.
|
||||
|
||||
## Hand work to Enso and Kai
|
||||
|
||||
@@ -90,9 +90,19 @@ hanzo dev · session summary
|
||||
|
||||
Figures are labelled with their source and are never added across sources. Nothing in the block claims a speedup.
|
||||
|
||||
## Desktop apps and editors
|
||||
|
||||
Claude Desktop, Cursor, VS Code, Windsurf, Zed, JetBrains and the Codex and Claude Code apps take the same toolset as an MCP server, and can run their own models on your Hanzo plan: [Desktop apps and editors](/docs/guides/coding/desktop).
|
||||
|
||||
## How Kai and the toolset measure
|
||||
|
||||
Every number Hanzo publishes about Kai and the toolset is a research run, with each item stored beside it. [hanzo.ai/benchmarks](https://hanzo.ai/benchmarks) draws them live: Kai against other decision models, and the [agent toolset board](https://hanzo.ai/benchmarks#tools), where the injection screen, the command guard, tool selection and log triage each sit beside the handler they replaced, every table linking its runs.
|
||||
Every number Hanzo publishes about Kai and the toolset is a research run, with each item stored beside it.
|
||||
|
||||
- **Hanzo Dev against Claude Code**, 44 held repair tasks ([runs](https://api.hanzo.ai/v1/research/runs?org=hanzo&benchmark=coding.repair)): Claude Code solved 44 at a 9.6 s median with 3.8 model calls a task; Hanzo Dev solved 40 at 2.2 s with 1.0. On the 40 both solved, Hanzo Dev was 3.8× faster, and 8.2× on the 24 that were search.
|
||||
- **The toolset's local tools** ([command](https://api.hanzo.ai/v1/research/runs?org=hanzo&benchmark=mcp.command), [select](https://api.hanzo.ai/v1/research/runs?org=hanzo&benchmark=mcp.select), [triage](https://api.hanzo.ai/v1/research/runs?org=hanzo&benchmark=mcp.triage)): the command guard answers in 0.06 ms, tool selection in 0.16 ms (top-1 .73), log triage in 0.37 ms (.70 right), each where the model call it replaced took 0.5 to 1.6 s.
|
||||
- **Kai** ([runs](https://api.hanzo.ai/v1/research/runs?org=hanzo&benchmark=latency)): 19.8 ms p50 for one decision.
|
||||
|
||||
No study yet measures an agent such as Claude Code with the toolset against the same agent without it. [hanzo.ai/benchmarks](https://hanzo.ai/benchmarks) draws them live: Kai against other decision models, and the [agent toolset board](https://hanzo.ai/benchmarks#tools), where the injection screen, the command guard, tool selection and log triage each sit beside the handler they replaced, every table linking its runs.
|
||||
|
||||
## Keep everything up to date
|
||||
|
||||
@@ -101,7 +111,7 @@ hanzo upgrade # hanzo, hanzo-mcp, dev and zt, and every coding a
|
||||
hanzo upgrade mcp qwen claude # just these
|
||||
```
|
||||
|
||||
`hanzo upgrade` runs [hanzo.sh](https://hanzo.sh) into the directory `hanzo` lives in, so the build that answers `hanzo` is the one that was upgraded. Each agent upgrades its own way: an npm agent is installed again under `~/.hanzo`, one with an updater of its own runs it (`claude update`, `codex update`, `cursor-agent update`, `agy update`, `goose update`, `grok update`, `hermes update`, `interpreter update`), and Aider and OpenHands are upgraded with `uv tool upgrade`. With nothing named, every agent installed that way is upgraded. Every Hanzo tool is a native binary for Linux and macOS on amd64 and arm64. `hanzo`, `dev` and `zt` also ship for Windows on amd64, from their GitHub release pages. `hanzo-mcp` does not: its browser bridge speaks a Unix socket, so on Windows `hanzo` runs each agent without the toolset and says so.
|
||||
`hanzo upgrade` runs [hanzo.sh](https://hanzo.sh) into the directory `hanzo` lives in, so the build that answers `hanzo` is the one that was upgraded. Each agent upgrades its own way: an npm agent is installed again under `~/.hanzo`, one with an updater of its own runs it (`claude update`, `codex update`, `cursor-agent update`, `agy update`, `goose update`, `grok update`, `hermes update`, `interpreter update`), and Aider and OpenHands are upgraded with `uv tool upgrade`. With nothing named, every agent installed that way is upgraded. Every Hanzo tool is a native binary for Linux and macOS on amd64 and arm64, and for Windows on amd64. On Windows, `npm install -g @hanzo/cli` installs `hanzo`, and `hanzo upgrade` fetches `hanzo-mcp`, `dev` and `zt` beside it, each checked against its published sha256.
|
||||
|
||||
## Options that apply to every agent
|
||||
|
||||
|
||||
@@ -9,6 +9,7 @@
|
||||
"codex",
|
||||
"cursor",
|
||||
"antigravity",
|
||||
"agents"
|
||||
"agents",
|
||||
"desktop"
|
||||
]
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user