ZCode, embroiled in a controversy over stealing user code, is now open source

简体中文 | English

ZCode is an AI coding workspace with desktop, browser, and terminal interfaces. This repository contains the clients, backend services, shared UI, and Agent CLI and runtime source code.

Install Git, Node.js 24.14.0, and pnpm 10.33.2. mise.toml is the source of truth for tool versions. Run all development and packaging commands below from the repository root.

pnpm bootstrap

pnpm bootstrap installs workspace dependencies, prepares local desktop runtime assets, and runs build:bootstrap.

The Agent CLI and runtime source code lives in apps/zcode-cli/ as a regular directory included when you clone this repository. No separate checkout or Git submodule initialization is required.

Additional setup and build commands:

The default bootstrap skips remote asset preparation and is suitable for local desktop development. Run the corresponding preparation command when working with remote workspaces or validating remote distribution assets.

pnpm dev:desktop

pnpm dev:desktop:test

pnpm dev:desktop defaults to pnpm dev:desktop:prod and uses production service configuration. The startup script prepares local runtime assets, builds the desktop Agent, then starts Electron and source watchers.

Set ZCODE_DATA_BASE_DIR to use a separate development data directory. For example, on macOS / Linux:

ZCODE_DATA_BASE_DIR="$HOME/.zcode-dev-home" pnpm dev:desktop:test

Use development mode when editing Web or backend source code:

pnpm dev:web

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

This starts both the Web development server (default: http://localhost:5173) and the backend (default: http://localhost:3030). Open the Web development server in your browser. /ws and general /api requests are proxied to the local backend; /api/v1/oauth/token is proxied separately to the configured product service.

After changing Agent source code, run pnpm --filter @zcode/cli... build and restart the service. To validate the complete distribution, extract and run it as described under Packaging → ZCode CLI distribution below.

The command-line distribution includes the TUI, Web client, and Agent behind one zcode command. With no arguments it starts the TUI; a leading --web starts Web mode; all other arguments go to the existing Agent CLI. Both modes run locally without Electron.

zcode

zcode --web

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

zcode --help
zcode --web --help

In Web mode, it uses the current directory as the workspace, listens on 127.0.0.1 without token authentication by default, selects an available port, and opens a browser. Use the URL printed in the terminal and press Ctrl+C to stop the service. For LAN access, use --host 0.0.0.0; listening on a non-local address generates an access token by default. Use the token-bearing URL printed in the terminal. Set a token with --token, or disable token authentication with --no-token.

When starting the general Web service's HTTP entry directly, configure API/WebSocket authentication with ZCODE_SERVER_AUTH_TOKEN. When creating the service programmatically, use the authToken option.

See Packaging below for build instructions. pnpm build:zcode only creates the distribution; it does not replace an existing zcode on PATH. If the command still points to an older installation or another checkout, check it with command -v zcode on macOS / Linux or where.exe zcode on Windows.

Use the source entry when developing the TUI or Agent:

pnpm --filter @zcode/cli dev --help
pnpm --filter @zcode/cli dev

pnpm --filter @zcode/cli... build
node apps/zcode-cli/packages/cli/dist/zcode.cjs --help

This entry runs the Agent CLI directly and does not handle the distribution's --web switch. Use pnpm dev:web for Web development, or the extracted bin/zcode.mjs shown below to test the unified command.

The root .env.example provides sample service URLs and build configuration. Copy it to .env as needed and place local overrides in .env.local. Select the Desktop development environment with dev:desktop:test or dev:desktop:prod.

Runtime variables can be set explicitly in the environment of the startup command. See config/README.md for the default configuration shipped with the client.

See third-party/README.md for notice generation, distribution checks, and where the notices are included in each distribution.

pnpm bundle:desktop

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

pnpm bundle:desktop -- --help

The default target is macOS arm64, and the default output directory is packages/desktop/dist/. --os accepts mac, win, or linux; --arch accepts x64 or arm64. Packaging and signing require the tools and configuration for the target platform.

Run pnpm build:zcode to build the CLI/TUI, backend, and Web client, collect the TUI native libraries, workers, and runtime dependencies, then assemble the distribution. Running the distribution still requires Node.js; use the version specified in mise.toml.

Before packaging, set the download base URL with ZCODE_DIST_BASE_URL in .env, .env.local, or the process environment, or pass it through --base-url. The URL below is a placeholder; replace it with your hosting URL when publishing:

pnpm build:zcode --base-url https://downloads.example.com/zcode/

pnpm build:zcode

pnpm build:zcode --skip-build

pnpm build:zcode --help

The version defaults to the root package.json version. Output is written to dist/zcode/:

• releases/<version>/zcode-<version>.tar.gz : runtime package.
• releases/<version>/sha256.txt : checksum file.
• latest.json andinstall.sh : version index and installer.

Upload the entire directory to the configured download base URL. The installer downloads the runtime package from that URL, installs it to ~/.zcode/runtime by default, and creates the zcode command in ~/.local/bin. Override these directories with ZCODE_DIST_HOME and ZCODE_DIST_BIN_DIR, respectively.

Existing Lite users should switch to the new build command, environment variables, and installer. Installation does not remove old Lite directories or migrate/delete session data.

To test a packaged build locally, extract and run it directly without up or installing it:

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

node dist/zcode/debug/zcode/bin/zcode.mjs --web \
  --workspace "$PWD" --port 3030 --no-open

Open http://127.0.0.1:3030 to validate the complete flow, with one backend serving the Web pages and running the Agent. The port must be available; if pnpm dev:web is already running, choose another --port.

See NOTICE.md for feature and promotion scope, maintenance policy, execution and data risks, licensing, and third-party copyright information.