glm_mcp_claude

# GLM-as-Subagent for Claude Code — plug & play > 📦 **Canonical source:** **https://github.com/djerok/glm_mcp_claude** — created by > [@djerok](https://github.com/djerok). If you found this via a fork, mirror, or an > awesome-list, the original lives here. Please ⭐ / file issues / open PRs at the source. Add **GLM** (Zhipu / Z.ai) to Claude Code as a **cheap, full-capability subagent** (~10× cheaper than Opus), with **automatic per-task routing** between Opus and GLM. Your main agent stays on Opus; GLM does the well-specified, cost-sensitive work — and can read, write, edit, and run your files directly. One command to install. > ✅ **Works in the Claude Code app on a subscription-based Claude.** Your main agent runs on the > Claude you already pay for through the **Claude Code app** (Pro / Max / Team subscription) — > **no separate pay-per-token Anthropic API key required**. Only GLM needs a (cheap) Z.ai key. > Opus orchestrates on your subscription; GLM does the heavy lifting for a fraction of the cost.  _{↑ The `glm` subagent (orchestrated by Haiku 4.5, the cheap layer) reading the repo and offloading the heavy work to GLM via the MCP tools — the Opus → Haiku → GLM hybrid in action.} ```bash # no clone needed — run straight from GitHub: npx github:djerok/glm_mcp_claude --key YOUR_ZAI_API_KEY # or clone and run the installer: node install.mjs --key YOUR_ZAI_API_KEY ``` …then restart Claude Code. That's it. (Details below.) > 🔑 **Your key must be from the Z.ai / Zhipu GLM Coding Plan.** Get one at > **https://z.ai** → subscribe to the **GLM Coding Plan**, then create an API key. A generic / > free key without coding-plan access will not work for the coding models used here. --- ## What you get - **`glm` subagent** — a full-tool subagent (read/write/edit/bash) powered by GLM. - **`glm_agent` tool** — GLM as a real file-editing agent with built-in oversight (diff, dry-run, git revert). - **`glm_delegate` / `glm_recommend` / `glm_status`** — draft-only delegation, a free routing advisor, and a health check. - **Auto-delegation hook** — when you spawn a subagent, it injects a GLM-vs-Opus verdict so cheap work goes to GLM automatically. Zero token cost when you're not spawning subagents. - **If you explicitly name an agent** ("use opus", "use the sonnet agent", "use glm"), the hook stays silent and just routes where you asked. --- ## Prerequisites - The **Claude Code app** (desktop or CLI), signed in with a **subscription-based Claude** (Pro / Max / Team). Your main agent uses this — **no Anthropic API key needed.** The `claude` CLI should be on your PATH (`claude --version`). - **Node.js ≥ 18** (`node -v`) - **A Z.ai / Zhipu API key with GLM Coding Plan access** — get one at **<https://z.ai>**. ⚠️ **It must be on the GLM Coding Plan** (the coding-plan subscription); a generic or free key won't have access to the coding models this uses. This is the **only paid key required**, and GLM is ~10× cheaper than Opus. - Git (optional, but enables `glm_agent`'s one-command revert) --- ## Install (recommended: global, all projects) ```bash # from this folder: node install.mjs --key YOUR_ZAI_API_KEY ``` The installer: 1. copies the server to `~/.claude/glm-mcp/` and runs `npm install`, 2. writes your key into `~/.claude/glm-mcp/.env`, 3. installs the `glm` subagent (`~/.claude/agents/glm.md`) and the hook (`~/.claude/hooks/`), 4. wires the hook into `~/.claude/settings.json` (backs it up first), 5. adds a short delegation policy to `~/.claude/CLAUDE.md`, 6. registers the MCP server with `claude mcp add glm -s user`. Then **restart Claude Code** and run `glm_status` — you should see `"api_key_loaded": true`. > Options: `--no-register` (skip the CLI step), `--skip-npm`, `--claude-dir PATH` (custom config dir). > Re-running is safe (idempotent). No key on the command line? Run `node install.mjs`, then edit > `~/.claude/glm-mcp/.env` and set `GLM_API_KEY=...`. ### Per-project instead of global Don't want it everywhere? Skip the installer. Copy `glm-mcp/` into your project, `cd glm-mcp && npm install`, copy `.mcp.json.example` → `.mcp.json` in the project root, set the key, and (optionally) copy `agents/glm.md` to `.claude/agents/` and the hook into `.claude/` + `.claude/settings.json`. --- ## How it works (the short version) ``` You ask for something → Opus orchestrates → wants to delegate a chunk → spawns a subagent → [hook fires] "[GLM router] GLM-suitable repo task → use glm_agent (dry_run first)" (or "keep on Opus" for hard/sensitive work) → Opus runs glm_agent (GLM edits the files, runs tests) — or keeps it on Opus → you get a diff + action log + a one-command revert ``` The routing rules live in **`glm-mcp/src/router.js`** and the **hook** — not in always-on context — so they cost nothing until a subagent is actually spawned. **Routing in one line:** GLM is the default (it's ~10× cheaper); Opus is the exception for work where being wrong is expensive — subtle debugging, architecture, large refactors, security, tool-heavy dependent loops, huge context, vision, or anything you mark sensitive. --- ## The tools | Tool | Cost | What it does | |---|---|---| | `glm_recommend` | free (local) | GLM-or-Opus decision + model pick + reasons. | | `glm_status` | free (local) | Peak window, active model, key/config health. | | `glm_delegate` | GLM tokens | Text in → text out. GLM drafts; you place it. | | `glm_agent` | GLM tokens | GLM works your repo directly (read/write/edit/bash). Returns a diff + action log + git revert; supports `dry_run` (propose, don't write). | ### Example: directly calling the GLM agent A real run — asking GLM (via `glm_agent`) to write a file end-to-end on disk:  > **Prompt:** *"Using the GLM agent `glm_agent`, write a 2000-word essay in Shakespearean format about the usefulness of an umbrella, into my Desktop."* GLM did it itself — created the file directly, no round-tripping the content through the main agent: - **Output:** `Umbrella-Essay-Shakespeare.md` — ~2,260 words of Early Modern English (*thee/thou/thy*, *doth/hath*) with two blank-verse interludes - **Work:** 18 tool-loop iterations; **one** file created, nothing existing touched - **Cost:** ~**$0.064** — a fraction of running the same task on Opus That's the point: the orchestrator stays on Opus while `glm_agent` does the heavy, file-touching work for cents. --- ## Oversight (how you stay in control of `glm_agent`) - **Entry:** you/Opus choose when to call it and with which `workdir`. - **`dry_run: true`:** GLM proposes a full diff and writes **nothing** — approve, then apply. - **After a real run:** you get the unified **diff**, an **action log**, and a one-command **git revert** (`git checkout <baseline> -- .`). Note: file/bash ops inside `glm_agent` run in the MCP server process (not gated per-edit) and are scoped to the `workdir` you pass. That's intentional (max autonomy) — point it only at repos you're fine letting it modify. --- ## Configuration (`~/.claude/glm-mcp/.env`) | Var | Default | Meaning | |---|---|---| | `GLM_API_KEY` | — | Your Z.ai key. **Required.** | | `GLM_BASE_URL` | `https://api.z.ai/api/anthropic` | Anthropic-compatible endpoint. | | `GLM_COST_BIAS` | `1.5` | How hard to favor GLM (it's ~10× cheaper). Higher = more GLM; `0` = decide on capability only. | | `GLM_CAP` | `off` | Output-token cap. **Off by default** = generous (up to 131072 per call). Set `on` to enforce `GLM_MAX_TOKENS` and rein in spend. | | `GLM_MAX_TOKENS` | `32768` | The hard per-call limit applied **only when `GLM_CAP=on`**. (`max_tokens` is a ceiling, not a target — you pay for actual output.) | | `GLM_MAX_TOKENS_CEILING` | `131072` | The generous default used when the cap is **off**. | | `GLM_MAX_CONCURRENT` | `1` | GLM caps in-flight requests; keep at 1. | | `GLM_OFFPEAK_MODEL` / `GLM_PEAK_MODEL` | `glm-5.2` / `glm-5.2` | Model(s) for `auto`. **Each can be a comma-separated list** (e.g. `glm-5.2,glm-5-turbo`) and the router auto-picks — most capable for hard tasks, cheapest for easy ones. **Peak rule:** when `auto` lands on a glm-5.x model (3× surcharge) the router routes **less** work to GLM at peak; if you include a no-surcharge model (e.g. `GLM_PEAK_MODEL=glm-5.2,glm-4.7`) it's preferred at peak and GLM stays fine to use. | | `GLM_PEAK_START_CN` / `GLM_PEAK_END_CN` | `14` / `18` | Peak window (China hour, UTC+8). | | `GLM_AGENT_MAX_ITERS` | `30` | Max tool-loop turns for `glm_agent`. | Full list with comments: `glm-mcp/.env.example`. --- ## Uninstall ```bash node uninstall.mjs # remove agent, hook, settings entry, MCP registration node uninstall.mjs --purge # also delete ~/.claude/glm-mcp (and its .env) ``` --- ## Security - **Never commit/share your `.env` or a `.mcp.json` containing the key.** `.gitignore` excludes them. - GLM routes through servers in China — don't send secrets/regulated code you wouldn't send to a third-party API. (Routing keeps `sensitive`-flagged work on Opus, but you decide what to delegate.) --- ## Troubleshooting | Symptom | Fix | |---|---| | `glm_status` missing / tools absent | Restart Claude Code; `claude mcp get glm` to confirm registration. | | `api_key_loaded: false` | Set `GLM_API_KEY` in `~/.claude/glm-mcp/.env`. | | Server fails to start | `cd ~/.claude/glm-mcp && npm run smoke` to see the real error. | | `Too much concurrency` | Expected under load; it auto-retries. Don't fan out parallel GLM calls. | | Hook not firing | Check `~/.claude/settings.json` has a `PreToolUse` `Task` matcher pointing at `glm_subagent_router.mjs`. | More background and the research behind the routing rules: see [`docs/`](docs/). --- ## Contributing PRs and issues welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). Good first areas: routing rules (`glm-mcp/src/router.js` + the hook), provider adapters, and docs. Please never commit secrets/`.env`. ## License [MIT](LICENSE) © [djerok](https://github.com/djerok) --- _{Original / canonical repository: **https://github.com/djerok/glm_mcp_claude**. If you fork, mirror, or redistribute this project, please keep a link back to the source so others can find updates, file issues, and contribute. Built by [@djerok](https://github.com/djerok).}