ZCode

ZCode is an open-source AI coding workbench structured as a monorepo. It supports three distinct execution targets: an Electron desktop app, a web browser interface, and a terminal TUI/Agent. The repository contains client applications, backend services, shared UI modules, and the agent runtime located directly in `apps/zcode-cli/`. ### System Requirements & Bootstrap ZCode relies on exact runtime versions pinned in `mise.toml`. You must use Node.js 24.14.0 and pnpm 10.33.2. To initialize the workspace and assemble local assets: ```bash pnpm bootstrap ``` This installs workspace dependencies, sets up local desktop resources, and triggers `build:bootstrap`. If you are developing for remote environments (over SSH or WSL), execute `pnpm bootstrap:with-remote`. This builds artifacts sequentially and prepares `packages/desktop/mock-cdn`. During remote sessions, these assets transfer via SFTP directly to the host without hitting external CDNs. ### Development & Runtime Architecture #### 1. Desktop Development To spin up the Electron application with source watching: ```bash pnpm dev:desktop ``` This runs `dev:desktop:prod` under the hood. It compiles the desktop Agent runtime before launching Electron. To isolate your development state, pass a distinct directory path: ```bash ZCODE_DATA_BASE_DIR="$HOME/.zcode-dev-home" pnpm dev:desktop:test ``` #### 2. Web & Backend Stack The web workspace uses a dual-process runner to serve both the frontend and API layers simultaneously: ```bash ZCODE_SERVER_WORKSPACE=/path/to/project pnpm dev:web ``` This starts the Vite development server on `http://localhost:5173` and the local backend on `http://localhost:3030`. The Vite server automatically proxies incoming WebSocket connections (`/ws`) and API calls (`/api`) to the backend, while routing OAuth requests (`/api/v1/oauth/token`) to configured product endpoints. If you modify the Agent CLI source code while working on the web target, recompile it using: ```bash pnpm --filter @zcode/cli... build ``` #### 3. Command-Line Interface (CLI & TUI) The standalone executable combines the Agent CLI, TUI, and Web server into a single binary called `zcode`. ```bash # Launch interactive terminal TUI zcode # Launch Web mode on a specific workspace and port zcode --web --workspace /path/to/project --port 3030 --no-open ``` In Web mode, the application binds to `127.0.0.1` by default without requiring an authentication token. If you expose the server over a network using `--host 0.0.0.0`, ZCode enforces token authentication automatically. You can explicitly set or disable tokens using `--token <token>` or `--no-token`. ### Architecture Review ZCode's design avoids external Git submodules by housing `apps/zcode-cli/` directly within the repository workspace. The isolation between local assets, remote SFTP asset pushes, and local proxying makes it a flexible foundation for developers building AI-assisted coding tools across terminal, web, and desktop environments.