Z Code for Linux

Unofficial Linux port of Z Code by Zhipu AI / CodeGeeX.

Work in Progress — This is a functional but incomplete port. The app launches, renders the full UI, and can run Claude Code directly via the CLI. Many features work, but some are stubbed or limited. See Current Limitations below.

How It Works

Z Code ships for macOS and Windows only. This project:

1. Extracts the frontend — A custom Rust tool parses the macOS Mach-O binary, locates the Tauri PHF asset map, and decompresses all 1344 brotli-compressed Next.js files
2. Wraps it in Tauri 2 — A Linux-native Tauri 2 shell (webkit2gtk) serves the extracted frontend and implements the IPC commands the frontend calls
3. Runs Claude directly — Instead of routing through Z Code's cloud WebSocket transport, the service_prompt command spawns the claude CLI locally and streams responses back to the UI via Tauri events
4. Patches the frontend — A bridge script connects Rust backend events to the frontend's Zustand notification store, so streamed responses appear in the chat UI

Architecture

┌─────────────────────────────────────────┐
│  Z Code Frontend (Next.js / Turbopack)  │
│  Extracted from macOS binary            │
├─────────────────────────────────────────┤
│  zcode-bridge.js                        │
│  Tauri events → notification store      │
├─────────────────────────────────────────┤
│  Tauri 2 Shell (Rust / webkit2gtk)      │
│  ~60 IPC commands, real PTY, agent mgmt │
├─────────────────────────────────────────┤
│  claude CLI (@anthropic-ai/claude-code) │
│  Spawned per prompt via --print mode    │
└─────────────────────────────────────────┘

Current Limitations

• Claude Code only — Only the Claude Code agent works (via local CLI). Gemini CLI, Codex, and OpenCode agents are not yet wired up
• No streaming — Responses appear all at once after the CLI finishes, not token-by-token
• No OAuth login — The "Continue with Z.ai" / "Continue with Bigmodel.cn" login buttons don't work because the zcode:// deep-link callback isn't registered on Linux. You can use Claude Code without logging in (it uses your local ANTHROPIC_API_KEY)
• No Z Code cloud features — The WebSocket transport to wss://zcode.z.ai/ws is not implemented. Features that depend on the Z Code backend (mobile pairing, cloud sessions, etc.) don't work
• Stubbed commands — Browser preview, SSH remote, some git operations, and MCP server configuration are stubbed (they accept calls but don't do anything)
• No auto-update — The app won't auto-update; new versions are published as GitHub Releases via CI

Install

AppImage (universal)

chmod +x z-code-linux_*.AppImage
./z-code-linux_*.AppImage

Debian / Ubuntu

sudo dpkg -i z-code-linux_*.deb

Fedora / RHEL

sudo rpm -i z-code-linux-*.rpm

Arch Linux (AUR)

makepkg -si

Build from Source

# Prerequisites: rust, cargo, 7zip, webkit2gtk-4.1, gtk3, libayatana-appindicator
cargo install tauri-cli --version "^2"

# Extract frontend from macOS DMG (downloads ~356MB)
bash scripts/download-extract.sh

# Build
cargo tauri build

Prerequisites

• Claude Code CLI: npm install -g @anthropic-ai/claude-code
• ANTHROPIC_API_KEY: Set in your environment for Claude to work
• System deps (Arch): pacman -S webkit2gtk-4.1 gtk3 libayatana-appindicator 7zip
• System deps (Ubuntu): apt install libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev 7zip

CI Pipeline

• check-update.yml: Runs daily, queries Z Code's update API for new upstream releases
• build-linux.yml: Downloads macOS DMG, extracts frontend, applies Linux patches, builds Tauri app, publishes .deb/.rpm/AppImage to GitHub Releases

Disclaimer

This is an unofficial community project and a work in progress. Z Code is proprietary software by Zhipu AI / CodeGeeX. All rights to Z Code belong to Zhipu AI. This project does not distribute any Z Code binaries — it extracts the frontend at build time from the official macOS release.