# ZCode: Z.ai's Open-Source AI Coding Agent for Desktop, Web, and Terminal

> zai-org/ZCode is the open-source repository for ZCode, an AI coding workbench from Z.ai that ships as an Electron desktop app, a browser-based interface, and a terminal agent. The codebase includes the client, backend server, shared UI, and the Agent CLI runtime, all in a single TypeScript pnpm monorepo.

**zai-org/ZCode** — Z.ai's coding agent harness. Powerful, intelligent, extensible.

- Repository: https://github.com/zai-org/ZCode
- Website: https://zcode.z.ai/
- Stars: 7,160 · Forks: 2,169
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/zai-org-zcode

## What ZCode Is and the Three Modes It Runs In

ZCode is described in the README as an AI programming workbench providing a desktop application, a browser interface, and a terminal agent. It targets developers who want an AI coding assistant that works across contexts: a native Electron app for desktop use, a browser-accessible web interface for remote or SSH sessions, and a command-line TUI for terminal-first workflows.

All three modes are driven by the same underlying agent runtime. The unified zcode binary handles the distinction: running zcode with no arguments opens the terminal TUI; zcode --web starts the web server; other arguments pass through to the existing agent CLI. The web mode and the desktop mode share the same backend service, so the agent behavior is consistent across surfaces.

The repository is from Z.ai (zai-org), the organization behind the z.ai platform. The codebase is open-source under Apache-2.0. The latest release is v3.14.3, published on 2026-09-24.

## Monorepo Layout and Package Responsibilities

ZCode is a pnpm workspace monorepo. The packages/ directory contains the primary packages: desktop/ holds the Electron main, host, and renderer code plus desktop packaging scripts; web/ holds the browser client; server/ provides the HTTP and WebSocket service and remote connection handling; zcode-server-cli/ manages the standalone server startup and process lifecycle; ui/ holds shared React components, hooks, and Zustand state; and services/ handles business logic and persistence.

Additional packages in packages/ include shared/ and rpc/ for shared protocols and a typed RPC framework, client/ for the agent client SDK, and provider/ with provider-node/ for the provider abstraction layer and its Node.js implementation. The Agent CLI source code lives in apps/zcode-cli/, cloned as part of the main repository with no separate submodule step required.

Configuration files at the root include mise.toml (pinning Node.js and pnpm versions), .env.example (service URLs and build configuration), DESIGN.md, CONTEXT.md, and AGENTS.md. The architecture policy is in architecture-policy.yaml, enforced by the verify:pre-push script.

## Building and Running ZCode from Source

The README specifies Node.js 24.14.0 and pnpm 10.33.2 as required versions, with mise.toml as the authoritative reference. To initialize the full workspace:

```bash
pnpm bootstrap
```

This installs workspace dependencies, prepares desktop local runtime assets, and runs the build:bootstrap script. For desktop development:

```bash
pnpm dev:desktop
```

This starts the Electron application using the production service configuration by default. To use the test environment instead:

```bash
pnpm dev:desktop:test
```

For browser-based development, the web development server and local backend start together:

```bash
pnpm dev:web
```

The web server defaults to http://localhost:5173 with the backend at http://localhost:3030. WebSocket and general API requests proxy to the local backend. The ZCODE_SERVER_WORKSPACE variable sets the backend's working directory:

```bash
ZCODE_SERVER_WORKSPACE=/path/to/project pnpm dev:web
```

A separate data directory for development can be set with ZCODE_DATA_BASE_DIR to avoid conflicts with an existing ZCode installation.

For developing the Agent CLI source directly, the README provides a separate entry point that runs the agent without going through the full distribution wrapper:

```bash
pnpm --filter @zcode/cli dev
```

After modifying agent source code, rebuild the CLI and its workspace dependencies with pnpm --filter @zcode/cli... build, then restart the web or desktop service to pick up the changes.

## The Command-Line Distribution Package

ZCode includes a build system that produces a distributable command-line package independent of Electron. The build script assembles the CLI, backend, and web frontend into a single tarball:

```bash
pnpm build:zcode
```

This requires the ZCODE_DIST_BASE_URL environment variable to be set to the base URL where the distribution will be hosted. The output goes to dist/zcode/, with a versioned tarball at releases/<version>/zcode-<version>.tar.gz, a sha256.txt checksum file, and latest.json and install.sh for the version index and installation script.

The install.sh script downloads the tarball, installs it to ~/.zcode/runtime by default, and creates a zcode command in ~/.local/bin. The installation directory can be changed with ZCODE_DIST_HOME and the binary directory with ZCODE_DIST_BIN_DIR.

For local debugging of the built package without deploying to a download server:

```bash
zcode_version=$(node -p "require('./dist/zcode/latest.json').version")
mkdir -p dist/zcode/debug
tar -xzf "dist/zcode/releases/$zcode_version/zcode-$zcode_version.tar.gz" -C dist/zcode/debug
node dist/zcode/debug/zcode/bin/zcode.mjs
```

The CLI distribution is the right path for server or SSH use cases where Electron is not available. In web mode, the zcode command supports several flags documented in the README: --workspace sets the project directory, --port sets the listening port, --no-open suppresses automatic browser launch, and --host 0.0.0.0 enables LAN access. When listening on a non-localhost address, ZCode automatically generates an access token and prints the authenticated URL to the terminal. The token can be set manually with --token or disabled with --no-token.

```bash
zcode --web --workspace /path/to/project --port 3030 --no-open
```

## Configuration and Environment Variables

The .env.example file documents the configuration surface. Key variables include ZCODE_DATA_BASE_DIR for the application data directory (data writes to a .zcode/ subdirectory beneath it), ZCODE_SERVER_WORKSPACE for the web backend's working directory, and ZCODE_BUILTIN_PROVIDER_CONFIG_FILE for a local provider configuration file that overrides the built-in settings. Setting ZCODE_BUILTIN_PROVIDER_CONFIG_FILE to a local file path completely replaces the built-in provider configuration, which is useful for organizations routing requests through a private API endpoint.

For the command-line distribution, ZCODE_DIST_BASE_URL sets the download root address used by the install script and must be set before running build:zcode. The ZCODE_SERVER_AUTH_TOKEN variable configures API and WebSocket authentication when the HTTP server is started directly. The web mode generates an access token automatically when listening on a non-localhost address; the token appears in the terminal output.

The .env.example shows the production service URLs for Z.ai's hosted infrastructure: ZCODE_BASE_URL, ZAI_OAUTH_ORIGIN, and BIGMODEL_API_BASE_URL. Local overrides can go in .env.local, which is not tracked by git.

## Desktop Build and macOS Installation

The desktop packager targets macOS arm64 by default. To build for other platforms:

```bash
pnpm bundle:desktop -- --os win --arch x64
```

The --os flag accepts mac, win, or linux. The --arch flag accepts x64 or arm64. Output goes to packages/desktop/dist/. The README notes that local builds are not signed, and on macOS the Gatekeeper may block the first launch. The workaround is:

```bash
sudo xattr -rd com.apple.quarantine /Applications/ZCode.app
```

Actual signing and notarization for distribution require platform-specific tools and credentials that are outside the scope of the repository documentation.

## ZCode Versus Claude Code: A Direct Comparison

The search data shows ZCode is frequently compared to Claude Code, and the comparison is direct. Both are AI coding agents that run in the terminal and can work with a local codebase. Claude Code is Anthropic's CLI for the Claude model, operating as a terminal agent without a built-in web interface or desktop application. ZCode adds a desktop Electron app and a browser-based web interface alongside the terminal agent, and integrates with Z.ai's model infrastructure (GLM/Bigmodel). This means ZCode is a broader surface area for the same core task.

The architectural difference is significant for teams who need remote or SSH access to an AI coding agent: ZCode's web mode (zcode --web) runs a local server accessible from a browser, which Claude Code does not have as a built-in feature. The LAN access option (--host 0.0.0.0) with token authentication means ZCode can serve a team on a local network without deploying to a cloud server. For terminal-only use cases, the functional scope is similar. ZCode is Apache-2.0; Claude Code is a closed-source proprietary tool, so ZCode is the choice for organizations that want to read or modify the agent implementation.

The search data also shows comparisons to Cursor, which is a GUI code editor with integrated AI rather than a terminal agent or web workbench. The distinction is that Cursor replaces or extends a code editor (based on VS Code), while ZCode is a separate workbench that operates on a project directory through a chat or TUI interface. Engineers who prefer staying inside a single editor environment would lean toward Cursor; those who want a separate AI workbench with web or desktop flexibility would consider ZCode.

## Conclusion

Developers who want to run ZCode from source for local extension or contribution work should start with pnpm bootstrap and the dev:desktop or dev:web commands documented in the README. The project requires Node.js 24.14.0 and pnpm 10.33.2 as pinned in mise.toml. Teams who only want to use ZCode rather than build it can use the prebuilt desktop installer or the command-line distribution package. The Apache-2.0 license permits use, modification, and distribution, with attribution required. The last release was v3.14.3 on 2026-09-24.

## FAQ

### Is ZCode better than Claude Code?

They target the same core use case (AI coding assistance in the terminal) but differ in deployment surface. ZCode adds an Electron desktop app and a browser-based web mode (zcode --web) alongside the terminal agent, and uses Z.ai's model infrastructure. Claude Code is a terminal-only CLI. ZCode is Apache-2.0 open source; Claude Code is proprietary.

### How do I install ZCode?

For development from source, run pnpm bootstrap after cloning, then pnpm dev:desktop or pnpm dev:web. For a command-line distribution, run pnpm build:zcode (with ZCODE_DIST_BASE_URL set) and then run the install.sh script from the dist/zcode/ output. Node.js 24.14.0 and pnpm 10.33.2 are required as specified in mise.toml.

### What is ZCode?

ZCode is an AI coding workbench from Z.ai that provides a desktop application, a browser interface, and a terminal agent in one package. The repository at zai-org/ZCode contains the full source under Apache-2.0, including the Electron desktop app, the web client, the backend server, shared UI, and the Agent CLI runtime.

## Sources

- [Issues](https://github.com/zai-org/ZCode/issues)
- [License: Apache-2.0](https://github.com/zai-org/ZCode/blob/main/LICENSE)
- [Project website](https://zcode.z.ai/)
- [README](https://github.com/zai-org/ZCode/blob/main/README.md)
- [zai-org/ZCode on GitHub](https://github.com/zai-org/ZCode)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/zai-org-zcode