📝 Tutorials
· 8 min read

How to Set Up ZCode with GLM-5.2: Install, Configure, First Goal

ZCode is a desktop application, not a terminal tool. The setup process looks different from tools like Claude Code or MiMo Code. You download an installer, connect your subscription, and configure your workspace visually.

This guide walks through every step: downloading ZCode, connecting your GLM Coding Plan, creating your first Goal, setting up SSH remote development, and configuring remote control. By the end, you will have a fully functional ZCode installation ready for real work.

If you are not sure whether ZCode is right for you, read our ZCode overview or the comparison with Claude Code first.

Prerequisites

You need:

  • A computer running macOS, Windows, or Linux (Linux is beta)
  • A Z.ai account (free to create at z.ai)
  • A GLM Coding Plan subscription (~$10 to $30/month)
  • At least 2GB free disk space
  • A stable internet connection

Step 1: Create a Z.ai Account

If you do not already have one:

  1. Visit z.ai
  2. Click “Sign Up”
  3. Register with email or phone number
  4. Verify your account

Z.ai accounts are free. The subscription for ZCode is separate.

Step 2: Subscribe to GLM Coding Plan

ZCode requires an active GLM Coding Plan. Without it, the app downloads but will not connect to the model.

  1. Log into your Z.ai account
  2. Navigate to “Plans” or “Subscriptions”
  3. Select “GLM Coding Plan”
  4. Choose your tier:
    • Basic (~$10/month): Standard usage limits, single-agent
    • Pro (~$20/month): Higher limits, multi-agent support
    • Team (~$30/month per seat): Collaboration features, priority support
  5. Complete payment

Your subscription activates immediately. You will receive a confirmation email with your plan details.

Step 3: Download ZCode

Download from the Z.ai website or directly:

macOS:

  • Visit z.ai/zcode/download
  • Download the .dmg file
  • Open the .dmg and drag ZCode to Applications
  • First launch: right-click > Open (to bypass macOS Gatekeeper on first run)

Windows:

  • Visit z.ai/zcode/download
  • Download the .exe installer
  • Run the installer
  • Follow the setup wizard
  • ZCode appears in your Start menu

Linux (Beta):

  • Visit z.ai/zcode/download
  • Download the .AppImage or .deb package
  • For AppImage: chmod +x ZCode.AppImage && ./ZCode.AppImage
  • For Debian/Ubuntu: sudo dpkg -i zcode.deb

Linux support is in beta. Ubuntu 22.04+ and Fedora 38+ are the best-tested distributions. Other distros may have issues.

Step 4: First Launch and Login

Open ZCode. You will see a login screen.

  1. Enter your Z.ai account credentials
  2. ZCode verifies your GLM Coding Plan subscription
  3. You arrive at the main workspace

If login fails, verify:

  • Your subscription is active (check z.ai account page)
  • Your internet connection is working
  • You are using the correct credentials

Step 5: Configure Your Workspace

ZCode needs to know where your code lives.

  1. Click “Add Project” or the + button
  2. Navigate to your project directory
  3. Select the root folder

ZCode scans the project structure and indexes files. For a standard web project, this takes a few seconds. For large monorepos, allow up to a minute.

You can add multiple projects. Switch between them from the sidebar.

Project Settings

For each project, configure:

  • Language/Framework: ZCode auto-detects but you can override
  • Build command: How to build your project (npm run build, cargo build, etc.)
  • Test command: How to run tests (npm test, pytest, etc.)
  • Ignored paths: Directories to skip (node_modules, .git, build output)

These settings help the agent execute tasks correctly and run verifications.

Step 6: Create Your First Goal

Now the interesting part. Goals are how you get work done in ZCode.

  1. Click “New Goal” or press Cmd+N (Ctrl+N on Windows/Linux)
  2. Type your objective in natural language:
Add a health check endpoint at GET /health that returns 200 with a JSON body containing status: "ok" and a timestamp field.
  1. Click “Plan” or press Enter

ZCode analyzes your project and generates a plan:

Step 1: Identify the router/controller pattern used in this project
Step 2: Create the health check route handler
Step 3: Register the route in the main router
Step 4: Add a test for the new endpoint
Step 5: Run tests to verify

  1. Review the plan. You can:

    • Approve it (click “Execute” or press Enter)
    • Edit specific steps
    • Add constraints (“do not modify the existing test file, create a new one”)
    • Reject and rephrase your Goal

  2. Click “Execute”

ZCode works through each step. After each step, you see a checkpoint with:

  • Files changed (with visual diffs)
  • Commands run
  • Current progress
  • “Continue” or “Adjust” buttons
  1. Review each checkpoint and continue until the Goal completes.

Tips for Writing Good Goals

Be specific about outcomes:

  • Good: “Add JWT authentication middleware that validates tokens from the Authorization header and returns 401 for invalid/missing tokens”
  • Vague: “Add auth”

Include constraints when needed:

  • “Use the existing database connection, do not create a new one”
  • “Follow the same file structure as the existing endpoints”
  • “Write tests using the Jest framework already configured in this project”

State what you do NOT want:

  • “Do not install new dependencies if possible”
  • “Do not modify the existing user model”

Step 7: Set Up SSH Remote Development

To work against remote servers:

  1. Open Settings (gear icon or Cmd+,)
  2. Navigate to “SSH Connections”
  3. Click “Add Connection”
  4. Enter:
    • Host: your-server.example.com
    • Port: 22 (or your custom port)
    • Username: your-user
    • Authentication: SSH key (recommended) or password
    • Key file: ~/.ssh/id_rsa (or your key path)
  5. Click “Test Connection”
  6. If successful, click “Save”

Once connected, you can add remote directories as projects. ZCode reads and writes files on the remote machine and executes commands there.

SSH Tips

  • Use SSH keys instead of passwords (more secure, no repeated prompts)
  • Ensure your SSH key is added to the remote machine’s authorized_keys
  • For machines behind a bastion/jump host, configure ProxyJump in your SSH config and ZCode will respect it
  • Keep your SSH connection stable (consider using ServerAliveInterval in ssh config)

Step 8: Configure Remote Control

Remote control lets you manage ZCode from your phone via messaging apps. We have a dedicated Telegram tutorial for the full walkthrough, but here is the quick version:

  1. Open Settings > Remote Control
  2. Choose your messaging platform (Telegram, WeChat, or Feishu)
  3. For Telegram:
    • Click “Connect Telegram”
    • Scan the QR code with your Telegram app, or enter the bot token
    • Send a verification code to confirm the link
  4. Enable notifications for:
    • Goal completion
    • Checkpoint approval requests
    • Errors and failures
  5. Test by sending a message to the ZCode bot from your phone

Once configured, you can start and manage Goals from your messaging app without being at your computer.

Understanding the Interface

ZCode’s main interface has several panels:

Left sidebar: Project file tree, search, and navigation

Center panel: Active Goal progress, code diffs, and editor

Right sidebar: Goal history, checkpoints, and agent status

Bottom panel: Integrated terminal, output logs, and test results

Top bar: Goal input, mode switching, and settings

You can resize, hide, or rearrange panels. The layout saves per project.

Workflow Patterns

Pattern 1: Define and Walk Away

For well-defined tasks:

  1. Create a detailed Goal
  2. Approve the plan
  3. Set checkpoint auto-approve (in Settings > Goals > Auto-approve simple checkpoints)
  4. Walk away
  5. Return to a completed Goal or review any flagged checkpoints

Pattern 2: Interactive Refinement

For tasks that need guidance:

  1. Create a Goal
  2. Review each checkpoint carefully
  3. Add adjustments at each checkpoint (“also handle the edge case where X is null”)
  4. Guide the agent through complex decisions

Pattern 3: Remote Kickoff

For starting work before you sit down:

  1. From Telegram: send a Goal description to ZCode bot
  2. ZCode generates a plan and sends it to you
  3. Reply with “approve” from your phone
  4. Agent works while you commute
  5. Sit down to a completed or nearly-completed task

Common First-Day Issues

”Subscription not found” error

  • Check that your GLM Coding Plan is active on z.ai
  • Try logging out and back in
  • Ensure you used the same account for both ZCode login and subscription purchase

Slow project scanning

  • Large monorepos take time on first scan
  • Exclude node_modules, .git, and build directories in project settings
  • Subsequent launches are faster (cached)

Goals fail immediately

  • Verify your build/test commands are correct in project settings
  • Check that the project builds successfully outside ZCode
  • Ensure the integrated terminal has the correct PATH (configure in Settings > Terminal)

SSH connection drops

  • Configure ServerAliveInterval 60 in your local SSH config
  • Check network stability
  • Try the connection in a regular terminal first to isolate the issue

Next Steps

Once you are set up:

  • Try progressively more complex Goals to understand ZCode’s strengths
  • Set up Telegram remote control for mobile management
  • Read our ZCode vs Claude Code comparison to understand trade-offs
  • Explore multi-agent coordination for large Goals (Pro plan required)
  • Check the three-way comparison to see how ZCode fits the current landscape

FAQ

Can I use ZCode without a GLM Coding Plan?

No. The app requires an active subscription to connect to GLM-5.2. Without it, you cannot create or execute Goals.

Does ZCode work with projects in any programming language?

Yes. ZCode supports any language that GLM-5.2 can handle, which includes all major programming languages. The integrated tools (build, test, lint) need to be configured per-project for your specific stack.

How do I update ZCode?

ZCode checks for updates on launch. When an update is available, it prompts you to install. On macOS, it downloads and replaces the app. On Windows, it runs an update installer. On Linux, download the new package manually.

Can multiple people use ZCode on the same project?

Yes, with the Team plan. Multiple developers can have their own ZCode instances pointed at the same repository. Goals and checkpoints are per-user and do not conflict. Git handles the actual code merging.

What happens to my Goals if my subscription lapses?

Your Goal history and project configuration remain locally. But you cannot create or execute new Goals until you renew. Existing checkpoints and code changes are preserved in your project directory.

You might also like

How to Install and Set Up MiMo Code: Mac, Linux, and Windows

Step-by-step guide to installing MiMo Code, configuring your model backend, running your first task, and optimizing settings for daily use.

How to Run GLM-5.2 Locally: Hardware, Quantization, and Setup Guide (2026)

Run Z.ai's GLM-5.2 (744B MoE, 40B active) locally with Ollama or llama.cpp. Hardware requirements, quantization options, and practical alternatives.

How to Run MiniMax M2.7 Locally: Hardware, GGUF Setup, and Performance Guide (2026)

Run MiniMax M2.7 (230B MoE, 10B active) locally with Ollama or llama.cpp. GGUF quantization options, hardware requirements, and speed benchmarks.

ZCode Remote Control: Trigger Coding Tasks from Telegram

How to set up ZCode remote control via Telegram, start Goals from your phone, monitor progress, and manage coding tasks without sitting at your computer.