100% private · no tracking · works offline100% client-side/no data leaves your browser/no accounts/works offline
A step-by-step walkthrough of installing ZCode, configuring Z.ai's open-weight GLM-5.2 model, running Goal Mode and MCP, and calling the API directly — plus how it stacks up against Claude Code, Cursor, and GitHub Copilot.
By Amaresh Adak13 min readFree toolkit
85+ private dev tools
Everything runs in your browser. Zero tracking, no sign-up.
Browse toolsEvery few months another coding agent shows up promising to be the "open" alternative to Claude Code or Cursor. Most of them are wrappers around someone else's model with a nicer UI. ZCode, the free desktop agent Z.ai shipped on July 2, 2026, is different in one important way: it's built end-to-end around GLM-5.2, a 753-billion-parameter model Z.ai released under an MIT license, and Z.ai controls both the harness and the weights. That combination — a serious open-weight model plus a purpose-built agent — is why ZCode is getting attention from teams who want an alternative to subscription-locked coding agents without giving up long-horizon, multi-file agentic workflows.
The problem is that most of the coverage of ZCode so far is either marketing narrative or comparison-table punditry. Nobody has walked through actually installing it, wiring up an API key, running a Goal Mode session, connecting MCP servers, or calling GLM-5.2 directly from your own code. That's what this guide does.
In this guide, we'll take a look at:
These are two separate things that Z.ai ships together, and it's worth keeping them distinct.
GLM-5.2 is the model. It's a 753B-parameter open-weight model released under an MIT license on June 13, 2026, tuned specifically for long-horizon coding and agentic tool use. On SWE-bench Pro it scores 62.1%, ahead of its predecessor GLM-5.1 (58.4%) and ahead of OpenAI's GPT-5.5 (58.6%). On MCP-Atlas, a benchmark for agentic tool use, it scores 77.0 — close to Claude Opus 4.8's 77.8 and ahead of GPT-5.5's 75.3. Because the weights are open, you can also run GLM-5.2 through OpenRouter, self-host it, or call it through Z.ai's own API.
ZCode is the agent harness — an Electron desktop app with a chat interface, file manager, integrated terminal, Git panel, and a live browser preview, tuned specifically to drive GLM-5.2. It's free to download; you pay separately for model access through a GLM Coding Plan, OpenRouter, or your own API key. Its standout feature is Goal Mode, which turns a task into a persistent, resumable objective the agent iterates on — plan, implement, test, fix — until it passes or hits a blocker.
If you've used Claude Code or Cursor, the mental model is familiar: ZCode is the harness, GLM-5.2 is the model, the same way Claude Code is a harness that happens to default to Claude models. The difference is that ZCode's harness and model are both controlled by the same company and both are cheap or free to get started with.
ZCode currently ships as a desktop app for macOS (Apple Silicon and Intel) and Windows (x64), with Linux available through a beta channel. As of this writing the latest version is v3.3.4.
macOS
# Download the .dmg from https://zcode.z.ai/en, then:
open ~/Downloads/ZCode.dmg
# Drag ZCode.app into /Applications, then launch it
# from Launchpad or:
open -a ZCode
Windows
Download the installer from https://zcode.z.ai/en, run it, and accept the default install location. ZCode will appear in the Start menu.
Linux (beta)
Linux builds are distributed through Z.ai's Linux beta group — join the waitlist from the ZCode download page to get access to the AppImage build.
Launching from the command line
Once installed, ZCode can also be launched from a terminal inside a project directory, which is the more useful workflow for anyone used to claude or cursor .:
cd ~/projects/my-app
zcode .
ZCode itself doesn't require payment — the app is free. What costs money is the model access behind it. You have three realistic options:
To get a key: create an account at z.ai, go to the API Keys section of your dashboard, and generate a key. Keep it out of source control — put it in a shell profile or an untracked .env file, not in a committed config.
export ZAI_API_KEY="your-key-here"
On first launch, ZCode will prompt you to paste this key in, or you can set it under Settings → Model Provider inside the app.
Goal Mode is the feature that separates ZCode from a plain chat-with-your-codebase tool. You give it an objective, and it treats that objective as a session-level runtime object it keeps working against — planning, writing code, running tests, and fixing failures — until the objective is verifiably met or it hits something it needs a human to unblock.
Open a repository in ZCode, then in the agent chat panel:
/goal Add input validation to the signup form in src/components/SignupForm.tsx.
Reject empty emails and passwords under 8 characters, show inline error messages,
and add a test file covering both cases. Run the test suite when done and fix
any failures before reporting back.
While a goal is running, you have a small set of subcommands to control it:
/goal pause # pause execution without losing state
/goal resume # continue a paused goal
/goal replace # swap in a new objective without starting a new session
/goal clear # abandon the current goal
The practical difference from a normal prompt-response loop: if GLM-5.2 writes a test that fails, Goal Mode doesn't stop and hand the failure back to you — it reads the failure output, adjusts the implementation, and re-runs the tests on its own, the same iterate-until-green loop you'd get from Claude Code's autonomous mode.
ZCode supports the Model Context Protocol, and ships with three built-in MCP services, including zai-mcp-server for visual understanding (so the agent can reason about screenshots and images you drop into a session).
To add your own MCP server, open Settings → MCP Servers and add a JSON entry in the same shape Claude Code and other MCP-compatible clients use:
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "your-token-here"
}
}
}
}
If you already have MCP servers configured in Claude Code, Codex CLI, or OpenCode, you don't have to redo this by hand — the MCP Servers page has an Import button that scans those tools' existing config files and pulls the entries into ZCode directly.
Because GLM-5.2 is OpenAI-compatible, you can call it from any tool or script that speaks the OpenAI Chat Completions format — you're not locked into the ZCode app at all. This is useful if you want to wire GLM-5.2 into an existing agent framework, CI script, or internal tool.
Python, using the OpenAI SDK
from openai import OpenAI
client = OpenAI(
api_key="your-Z.AI-api-key",
base_url="https://api.z.ai/api/paas/v4/",
)
response = client.chat.completions.create(
model="glm-5.2",
messages=[
{"role": "system", "content": "You are a senior Python engineer."},
{"role": "user", "content": "Write a function that validates a US phone number."},
],
)
print(response.choices[0].message.content)
curl
curl https://api.z.ai/api/paas/v4/chat/completions \
-H "Authorization: Bearer $ZAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "glm-5.2",
"messages": [
{"role": "user", "content": "Explain the difference between a mutex and a semaphore."}
]
}'
One gotcha worth flagging: the GLM Coding Plan subscription uses a different base URL than the general-purpose API — https://api.z.ai/api/paas/v4/coding instead of https://api.z.ai/api/paas/v4/ — and the two aren't interchangeable. If you subscribed to the Coding Plan specifically and your requests are failing with an auth or quota error against the general endpoint, this is almost always why.
Beyond Goal Mode and MCP, a few other features show up often enough in ZCode sessions that they're worth understanding before you rely on the tool for real work.
Multi-agent collaboration. ZCode can split a Goal across multiple sub-agents working in parallel — for example, one agent implementing a feature while another writes tests against the interface as it's built. You don't configure this manually; the orchestrator agent decides when a task is parallelizable and spawns sub-agents itself. If you want to force single-agent execution for a task where parallel edits would conflict (e.g., a large refactor touching shared state), say so explicitly in your goal description — the orchestrator respects that constraint.
SSH remote development. ZCode can run against a codebase on a remote machine over SSH rather than only local files, which matters if your dev environment lives on a beefier remote box or inside a company VPN. Configure this under Settings → Remote Development with a standard host/user/key setup, the same as VS Code's Remote-SSH extension.
Plugin architecture. ZCode supports plugins that extend the agent's available tools beyond MCP servers — things like custom linters, deploy scripts, or internal CLI wrappers your team already uses. Plugins live in a .zcode/plugins/ directory at the repo root and are picked up automatically on the next session start.
BYOK (bring your own key) beyond Z.ai. While ZCode is built around GLM-5.2, the model provider setting isn't hard-locked — you can point it at OpenRouter or another compatible provider if you want to run a different model through the same harness. This is useful for comparing GLM-5.2's output against another model on the exact same Goal without switching tools.
Deep context management. With a 1M-token context window, ZCode maintains state across long sessions rather than summarizing and dropping earlier context the way shorter-context agents have to. In practice this means a Goal that runs for an hour across a dozen files still has the full history of what it tried and why, which materially reduces the "the agent forgot what it already fixed" problem you get with smaller-context tools.
Safety and confirmation prompts. Destructive actions — deleting files, force-pushing, running a command outside the project directory — trigger an explicit confirmation prompt by default rather than executing silently. You can adjust the sensitivity of this under Settings → Permissions, similar to permission modes in Claude Code.
| ZCode + GLM-5.2 | Claude Code (Opus 4.8) | Cursor | GitHub Copilot (Kimi K2.7 Code) | |
|---|---|---|---|---|
| Model license | Open weight (MIT) | Closed | Closed | Open weight |
| Harness cost | Free | Free (pay per token) | Subscription | Included in Copilot plan |
| Coding plan pricing | $16.20–$144/mo | Pay-per-token or Max plan | $20–$200/mo | Included in $10–$39/mo Copilot plans |
| SWE-bench Pro | 62.1% | Not directly comparable (different eval) | N/A (model-dependent) | Varies by selected model |
| MCP-Atlas (tool use) | 77.0 | 77.8 (Opus 4.8) | Model-dependent | Model-dependent |
| MCP support | Yes, with import from other tools | Yes | Yes | Yes |
| Context window | 1M tokens | 1M tokens (Fable 5) / 200K (Opus 4.8) | Model-dependent | Model-dependent |
| Self-hosting option | Yes (open weights) | No | No | No |
Two things stand out. First, GLM-5.2's MCP-Atlas score (77.0) landing within a point of Claude Opus 4.8 (77.8) is the real headline — it means the gap between "best closed model" and "best open model" on agentic tool use has nearly closed, which wasn't true a year ago. Second, ZCode is the only option in this table you can self-host end-to-end, which matters if your organization has data residency requirements that rule out sending code to a third-party API at all.
That second point comes with a caveat worth stating plainly: if you use Z.ai's hosted API (rather than self-hosting the open weights yourself), your requests are subject to Chinese data regulations, since Z.ai is a Beijing-based company. For personal projects this is usually a non-issue; for regulated industries or enterprise codebases, it's a real factor to evaluate before you route production code through the hosted endpoint — self-hosting the open weights sidesteps this entirely.
"Model not found" or 404 errors calling the API directly. Almost always a base URL mismatch — check whether you're on a GLM Coding Plan (use the /coding endpoint) or a general API key (use the standard endpoint), and make sure model is set to glm-5.2 in lowercase.
Goal Mode gets stuck "waiting for input" indefinitely. This happens when the agent hits an ambiguous decision it's been told to escalate rather than guess — check the chat panel for a question it asked that scrolled out of view. /goal resume after answering will pick the session back up.
MCP servers imported from Claude Code don't show tools. The import copies the server config, not credentials stored in your OS keychain. Re-enter any API keys or tokens for imported servers under Settings → MCP Servers after importing.
Linux build won't launch after AppImage download. Make it executable first: chmod +x ZCode-*.AppImage, then run it directly rather than through a file manager double-click, which silently fails on some distros without a desktop integration daemon running.
If you're already deep into Claude Code or Cursor and happy with the results, GLM-5.2's benchmark scores aren't yet a strong enough reason to switch — a one-point gap on MCP-Atlas isn't something you'll feel day to day. Where ZCode earns a real look is if you're cost-sensitive, want the option to self-host, or need to route sensitive workloads through infrastructure you control rather than a vendor's closed API. The free harness plus MIT-licensed weights combination is genuinely new in this space, even if the day-to-day coding experience is still catching up to the incumbents in polish.
ZCode and GLM-5.2 aren't a novelty release — GLM-5.2's benchmark numbers put it within striking distance of Claude Opus 4.8 on agentic tool use, and ZCode wraps it in a harness with the same Goal Mode, MCP, and multi-agent patterns you'd expect from Claude Code or Cursor, at a fraction of the cost and with the option to self-host. The setup takes about ten minutes: install the app, get an API key, and run /goal against a real task in your own repo. That's the fastest way to tell whether it earns a permanent spot in your toolchain.
Comments
Sign in to join the discussion.
No comments yet. Be the first to share your thoughts.