A native Android client for ZCode Remote — an immersive, full-screen experience with no browser address bar or toolbars in the way.

English | 中文

• 🖥️ Immersive full screen — content fills the entire screen, with no browser address bar, toolbars, or menus
• 📷 QR code scanning — scan the QR code shown by ZCode on your desktop and connect instantly, no copy/paste needed
• 🔁 Auto-reconnect — the app remembers your last connection and reopens it on launch, so it's always ready to use
• 📋 Session management — save a connection URL once, then jump back in with one tap
• 🌐 English & Chinese — the interface follows your phone's system language (English is the default)
• 🎨 Dark theme — matches the zai-dark style of the ZCode Remote web app, easy on the eyes
• 🔄 Rotation-safe — rotating the screen does not reload the page (avoids re-downloading the large SPA bundle)
• 🔒 Local-only storage — session credentials stay in the app sandbox and are never uploaded anywhere

1. In ZCode on your desktop, open the Remote feature until the QR code shows (or copy the connection URL, which looks like https://zcode.z.ai/remote/v4?sid=...)
2. Open ZRemote and tap Scan QR Code — point the camera at the QR code. Alternatively, paste the URL manually and tap Connect
3. Enjoy the immersive full-screen session
4. On exit you can save the session; next time ZRemote reopens it automatically, so you are always connected and ready to go

⚠️ The connection URL carries one-time credentials (with a timestamp). When it expires you'll see AUTH_FAILED — just scan/copy a fresh URL from the desktop app.

• Android Studio (Hedgehog 2023.1.1 or newer)
• JDK 17
• Android SDK 34

# 1. Clone
git clone https://github.com/REVENTOR-EU/ZRemote.git
cd ZRemote

# 2. Build the debug APK
./gradlew assembleDebug

# Output: app/build/outputs/apk/debug/app-debug.apk

You can also open the project in Android Studio, let Gradle sync, and press Run.

app/src/main/java/com/zcode/client/
├── MainActivity.kt                  # Entry point: navigation + auto-reconnect
├── ui/
│   ├── SessionViewModel.kt          # Session list state
│   ├── theme/                       # Dark theme (Color / Type / Theme)
│   └── screen/
│       ├── ConnectScreen.kt         # Paste URL / scan QR connect screen
│       ├── ScanScreen.kt            # Camera QR scanner (CameraX + ML Kit)
│       ├── SessionScreen.kt         # Full-screen WebView session (core)
│       └── SessionListScreen.kt     # Saved sessions list
├── web/
│   ├── WebViewConfig.kt             # WebView settings (DOM Storage / cookies / wss)
│   └── ZCodeWebViewClient.kt        # WebViewClient (loading / error callbacks)
├── data/
│   ├── Session.kt                   # Data model
│   ├── SessionStore.kt              # DataStore persistence
│   └── UrlValidator.kt              # URL validation
└── res/
    ├── values/strings.xml           # English strings (default)
    └── values-zh/strings.xml        # Chinese strings

Every setting in WebViewConfig.kt is based on hands-on research of ZCode Remote — don't turn them off casually:

• Multiple server support (self-hosted / intranet ZCode deployments)
• File download / upload (WebView file chooser callbacks)
• Push notifications for new remote messages

MIT License © 2026 潘崇实 (PanCodeInventory)

This is a third-party client, not affiliated with ZCode.
All ZCode Remote features and trademarks belong to their respective owners.

一个为 ZCode Remote 打造的 Android 原生客户端，提供沉浸式全屏体验，告别浏览器地址栏与工具栏的干扰。

English | 中文

• 🖥️ 沉浸式全屏 —— 内容铺满整个屏幕，隐藏浏览器的地址栏、工具栏与菜单
• 📷 扫码连接 —— 扫描电脑端 ZCode 显示的二维码，直接连接，无需复制粘贴
• 🔁 自动重连 —— 记住上次的连接，打开 APP 自动恢复会话，随时可用
• 📋 会话管理 —— 粘贴一次连接 URL，保存后下次一键进入，无需重复复制
• 🌐 中英双语 —— 界面语言自动跟随手机系统语言（默认英文）
• 🎨 暗色主题 —— 对齐 ZCode Remote 网页的 zai-dark 风格，长时间使用不刺眼
• 🔄 横竖屏自适应 —— 横竖屏切换不重新加载页面（避免大体积 bundle 重载）
• 🔒 本地存储 —— 会话凭证仅存在应用沙箱内，不上传任何服务器

1. 在电脑端 ZCode 打开「远程」功能，显示二维码（或复制连接 URL，形如 https://zcode.z.ai/remote/v4?sid=...）
2. 打开 ZRemote，点「扫码连接」，对准二维码即可；也可以手动粘贴 URL 后点「连接」
3. 进入沉浸式全屏会话
4. 退出时可选择保存会话，下次打开 ZRemote 会自动恢复上次的连接，随时可用

⚠️ 连接 URL 带一次性凭证（含时间戳），过期后会提示 AUTH_FAILED，重新从电脑端扫码/复制最新的即可。

• Android Studio（Hedgehog 2023.1.1 或更新）
• JDK 17
• Android SDK 34

# 1. 克隆
git clone https://github.com/REVENTOR-EU/ZRemote.git
cd ZRemote

# 2. 构建 Debug APK
./gradlew assembleDebug

# 产物：app/build/outputs/apk/debug/app-debug.apk

也可以直接用 Android Studio 打开项目目录，Sync Gradle 后点 Run。

app/src/main/java/com/zcode/client/
├── MainActivity.kt                  # 入口：Navigation + 自动重连
├── ui/
│   ├── SessionViewModel.kt          # 会话列表状态管理
│   ├── theme/                       # 暗色主题（Color / Type / Theme）
│   └── screen/
│       ├── ConnectScreen.kt         # 粘贴 URL / 扫码连接页
│       ├── ScanScreen.kt            # 相机扫码页（CameraX + ML Kit）
│       ├── SessionScreen.kt         # WebView 全屏会话页（核心）
│       └── SessionListScreen.kt     # 已保存的会话列表
├── web/
│   ├── WebViewConfig.kt             # WebView 配置（DOM Storage / Cookie / wss）
│   └── ZCodeWebViewClient.kt        # WebViewClient（加载 / 错误回调）
├── data/
│   ├── Session.kt                   # 数据模型
│   ├── SessionStore.kt              # DataStore 持久化
│   └── UrlValidator.kt              # URL 校验
└── res/
    ├── values/strings.xml           # 英文文案（默认）
    └── values-zh/strings.xml        # 中文文案

WebViewConfig.kt 中每一项配置都基于对 ZCode Remote 的调研结论，请勿随意关闭：

• 多服务器支持（自建 / 内网 ZCode 部署）
• 文件下载 / 上传（WebView 文件选择回调）
• 推送通知（远端有新消息时提醒）

MIT License © 2026 潘崇实 (PanCodeInventory)

本项目为第三方客户端，与 ZCode 官方无隶属关系。
ZCode Remote 的所有功能与版权归官方所有。