ZCode ACP

简体中文 | English

The app for zcode-acp: drive the
agent sessions your machine runs, from a native desktop workbench, an Android
phone, or any browser. Every surface attaches to a zcode-acp Hub over
WebSocket; the transport contract is the server's
REMOTE-CLIENTS.md.

Two identifiers deliberately keep the historical zcode-acp-remote spelling
and must not be renamed casually: the desktop client's wire identity
(zcode-acp-remote-desktop, matched by the hub) and the desktop config
directory (~/.config/zcode-acp-remote).

Surfaces

The desktop workbench is a dock-style window: a rail of toggles, the sessions
panel docked beside a tabbed chat area, the active session's file browser on
the right, and a left overlay drawer — opened from the rail — for settings
and the full quota display, floating above the layout without displacing it.
The Android and web clients share one React codebase; the desktop client is
its own product line, not a port of it (ADR-0009). Both compile the same
i18n catalogs.

Features

Shared by every surface:

• Attach to existing sessions, or start new ones in any of the machine's known
  projects (bridge 0.17.0+), or browse the machine's directories for a target
  (bridge 0.65.0+)
• Streaming assistant replies with Markdown, syntax-highlighted code, and diff
  views
• Approve tool permissions and answer AskUserQuestion forms in the session that
  raised them — including requests that fired while the client was offline
  (re-delivered after reconnect)
• Per-session prompt queue whose drafts survive app restarts
• Session files: breadcrumb browser over the active session's directory tree,
  with a line-windowed text viewer, image preview, and a download fallback
• Configuration pages for the machine: models, usage statistics, plan quota and
  its reset cards, system status, skills, MCP servers, hooks, subagents,
  backups, dynamic workflows, and app updates
• Plan-quota allowance windows with reset cards, and the account's usage
  statistics
• Reconnect with replay catch-up; transient drops stay quiet
• English / 简体中文 UI

Desktop-only:

• One tab per session, each with its own connection; ⌘1–9 switch tabs, ⌘K
  searches sessions, Esc stops the running turn
• Hub bootstrap — when no hub is listening the app spawns the installed
  zcode-acp-server daemon and connects to it (ADR-0010)
• Desktop Presence — while the workbench is connected, new sessions incubate
  headless instead of opening terminal windows (ADR-0010)
• Open the browsed folder or file in Zed, when the hub is local and Zed is
  installed (the action is absent otherwise)

Install

Android — grab the latest APK from Releases, sideload
it, and enter your Hub URL + token.

Desktop — build it yourself (no prebuilt download), see
Desktop workbench.

Web — deploy the SPA yourself, see
Standalone web deployment.

Server setup

Every surface is a client; you need a running zcode-acp-server hub:

1. Install and run zcode-acp-server
   on the machine whose agent sessions you want to drive.
2. Set a remote token (ZCODE_ACP_REMOTE_TOKEN) when starting the bridge if the
   hub is reachable from other machines.
3. Expose the hub over https:// (a tunnel works — the app upgrades https→wss
   itself) or use plain http:// on your LAN.

On the machine running the workbench the hub may be local: the desktop app
starts it when nothing is listening. A token is still required — when neither
the config file nor ZCODE_ACP_REMOTE_TOKEN carries one, the app shows a
guided setup card and writes the token it generates.

Development

pnpm install
pnpm dev                # browser at http://localhost:5173 (fastest loop)
pnpm tauri android dev  # on a device/emulator via adb
pnpm build              # type-check + bundle to dist/
pnpm test               # vitest

Desktop workbench:

cargo check  --manifest-path src-gpui/Cargo.toml
cargo test   --manifest-path src-gpui/Cargo.toml -p app

Android APK

pnpm build:android          # release APK -> dist/, needs a signing key
pnpm build:android:debug    # debug APK -> dist/, no key needed

Release builds are signed with a key in .signing/ (gitignored; create your
own keystore.jks + keystore.properties there). Identifier: app.zcode.acp
(immutable once installed).

The icon set is generated from scripts/gen-icon.mjs (SVG via sharp →
1024px source) — rerun
node scripts/gen-icon.mjs && pnpm tauri icon src-tauri/icons/app-icon.png
after changing the design.

Desktop workbench

./scripts/build-macos-gpui.sh   # or: pnpm build:macos -> dist/ZCode-acp.app

The native gpui workbench is the one desktop client — the old Tauri WebView
shell build is retired (the Tauri tree builds the Android app). Unsigned (no
Developer ID, no notarization): it runs as built on your machine; on another
machine Gatekeeper needs a one-time right-click → Open.

Standalone web deployment

The React client is a plain SPA — no Tauri APIs are used — so the web build
runs on iOS, desktop, and any other browser. Deploy it yourself; no backend of
your own is needed: the hub serves Access-Control-Allow-Origin: *.

One click (Netlify) — forks the repo into your own GitHub account and
builds it for you:

Cloudflare Pages — two ways:

• Git integration: fork the repo, then in the Pages dashboard connect it
  with build command pnpm build, output directory dist, and environment
  variable NODE_VERSION=22.
• Direct upload from your machine: pnpm deploy:web builds dist/ and
  pushes it to a Pages project in your own Cloudflare account — no Git
  integration needed. Copy .env.local.example to .env.local (gitignored)
  to set the API token and project name; without a token, wrangler's own
  login flow (pnpm dlx wrangler login) is used instead.

Any static host — the Netlify config ships in netlify.toml; Vercel
detects the Vite build automatically; or build locally and upload:

pnpm build              # -> dist/ (static, self-contained)
pnpm exec vite preview  # local smoke test of the built bundle

Served by the hub (same origin) — with static hosting enabled
(ZCODE_ACP_WEB_DIR or remote.webDir in the server config), the hub
serves the build itself: one address for the page, the REST API, and the
WebSocket — no CORS, no mixed-content limits, no separate static host; behind
a tunnel a single https URL covers everything.

pnpm build
ZCODE_ACP_WEB_DIR="$PWD/dist" zcode-acp hub   # then open http://localhost:8377

On the connect screen leave the hub URL empty — it defaults to the page's
origin, so only the token is needed.

Caveats:

• On a separately deployed page, https:// can only open wss:// — enter
  the hub's tunneled https:// URL.
• The token is stored in the browser's localStorage: don't use a shared
  machine, and prefer a private/incognito window for one-off access.

Releasing

pnpm release <version> bumps the version carriers, builds the Android APK,
commits, tags, pushes, and publishes the GitHub Release in one shot. The
desktop workbench is built and distributed separately (it has no signed
artifact channel). Details: docs/RELEASING.md.

Docs

• README.zh-CN.md — 简体中文文档
• CONTEXT.md — glossary for this context
• docs/adr/ — architecture decisions

License

MIT