简体中文 | 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. | Interface | Purpose | Development command | | ---------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------ | | Desktop | Electron desktop application | `pnpm dev:desktop` | | Web / ZCode CLI distribution | Terminal and browser workspace; packages the TUI, Web client, backend, and Agent together | `pnpm dev:web` | | Agent CLI | The `zcode` terminal interface, which also provides the Agent runtime for Desktop and Web | `pnpm --filter @zcode/cli dev` | ## Setup Install Git, Node.js **24.14.0**, and pnpm **10.33.2**. [mise.toml](mise.toml) is the source of truth for tool versions. Run all development and packaging commands below from the repository root. ```bash 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/](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: | Command | Purpose | | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- | | `pnpm install` | Install dependencies | | `pnpm prepare:desktop-runtime` | Prepare desktop runtime assets, including remote assets by default | | `pnpm prepare:remote-assets` | Prepare remote runtime assets separately | | `pnpm bootstrap:with-remote` | Set up dependencies and local and remote assets, then build the relevant packages sequentially; skip the desktop application bundle | | `pnpm build` | Recursively run each workspace package's build script, including its asset preparation steps | 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. ## Development and Usage ### Desktop ```bash pnpm dev:desktop # Use the test environment 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: ```bash ZCODE_DATA_BASE_DIR="$HOME/.zcode-dev-home" pnpm dev:desktop:test ``` ### Web Development Use development mode when editing Web or backend source code: ```bash pnpm dev:web # Set the backend workspace (macOS / Linux) 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. ### ZCode CLI distribution 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. ```bash # Start the terminal UI by default zcode # Start the Web interface zcode --web # Set the project and port without opening a browser automatically zcode --web --workspace /path/to/project --port 3030 --no-open # Show CLI or Web options 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. ### CLI Source Development Use the source entry when developing the TUI or Agent: ```bash pnpm --filter @zcode/cli dev --help pnpm --filter @zcode/cli dev # Build the CLI and its workspace dependencies 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. ## Configuration The root [.env.example](.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`. | Setting | Purpose | | ------------------------------------ | --------------------------------------------------------------------------------------- | | `ZCODE_DATA_BASE_DIR` | Base directory for application data, stored under its `.zcode/` subdirectory | | `ZCODE_SERVER_WORKSPACE` | Workspace path for the Web backend | | `ZCODE_BUILTIN_PROVIDER_CONFIG_FILE` | Path to a local provider configuration file; uses the built-in configuration when unset | | `ZCODE_DIST_BASE_URL` | Download base URL used by the CLI distribution installer | Runtime variables can be set explicitly in the environment of the startup command. See [config/README.md](config/README.md) for the default configuration shipped with the client. ## Packaging See [third-party/README.md](third-party/README.md) for notice generation, distribution checks, and where the notices are included in each distribution. ### Desktop ```bash pnpm bundle:desktop # Set the target platform and CPU architecture 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. ### ZCode CLI distribution 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: ```bash pnpm build:zcode --base-url https://downloads.example.com/zcode/ # When ZCODE_DIST_BASE_URL is already configured pnpm build:zcode # Repackage existing Agent, backend, and Web build outputs pnpm build:zcode --skip-build # Show options for the version, output directory, and more pnpm build:zcode --help ``` The version defaults to the root `package.json` version. Output is written to `dist/zcode/`: - `releases/