Android Client Notes

This project is based on the upstream tmux-browser documents under docs/, especially:

docs/api.md
docs/superpowers/specs/2026-04-17-browser-tmux-dashboard-design.md
docs/superpowers/specs/2026-04-21-pty-streaming-terminal-design.md
docs/superpowers/specs/2026-04-30-harmonyos-mobile-tmux-manager-design.md

What The Upstream Docs Say

The mobile design document is HarmonyOS-first and recommends a native ArkTS client with these modules:

connection profile store
session API client
terminal WebSocket client
terminal core
terminal view
shortcut bar
session list and terminal screens

It also says Android is second priority and WebView terminal rendering is out of scope for that first HarmonyOS version.

Android Request Reconciliation

The current request is different from that document in two important ways:

target platform is Android first
remote testing requires online APK builds and app-side update checks

For that reason, this repository starts with an Android API-client MVP. The existing server is expected to already be running on port 3000. The app calls the server HTTP API and terminal WebSocket directly instead of loading the existing browser UI.

This is not yet the full native-terminal architecture described by the HarmonyOS design document, but every exposed Android feature is native and calls the server API directly. There is no WebView fallback.

Backend Contract

The Android client must not change the server protocol.

HTTP:

GET /api/sessions
POST /api/sessions
DELETE /api/sessions/:name
POST /api/sessions/:name/input

WebSocket:

/ws/terminal
/ws/events
attach
input
resize
scroll
clear-history

The server remains the source of truth. Closing the app or terminal viewer must not kill a tmux session.

Current MVP

Implemented now:

configurable base URL, defaulting to http://100.89.0.116:3000
support for Tailscale URLs such as http://100.x.y.z:3000
native multi-page shell with Sessions, Tools, Update, and About
native session list from GET /api/sessions
create, rename, command send, split, pane select, pane kill, pin, mute, and kill session through documented session/preference endpoints
basic live terminal through /ws/terminal
native event stream through /ws/events
bottom shortcut bar for Esc, Tab, Ctrl+C, Ctrl+V, arrows, page keys, tmux prefix actions, and paste
shortcut delivery through the terminal WebSocket input message
native Tools page for health, server status, timeline, preferences, kanban projects, group messages, hook events, image file/URL upload, image preview metadata, and native image preview display
GitHub Actions APK build
release manifest latest.json
selected-source update checks; GitHub and Gitea are not probed in the same update check
one-download-per-version APK cache, SHA-256 verification, and installer handoff
permission/about surfaces for unknown-app install status, notification status, app version, package name, and API/protocol summary

Update And Release Policy

The Android app cannot silently replace itself. It may download a newer APK and open Android's package installer, but the user must approve the install. On Android 8+, the user may also need to allow this app to install unknown apps.

The app checks exactly one update source per run: the selected manifest/API URL. GitHub is the default public source. Gitea is available as a public mirror, but the app does not fall back across both providers during a normal check. This keeps update behavior predictable on mobile networks and avoids duplicate provider checks.

Downloaded APKs are cached by versionCode. If a cached APK exists and its SHA-256 matches the manifest, the app reuses it instead of downloading the same version again. This matters when Android redirects the user to unknown-app install settings before the installer can run. After the user grants that permission and returns to the app, the app resumes installation of the pending APK instead of asking the user to run update again.

Only v* tags publish GitHub Releases. Main branch builds and manual workflow runs are for CI artifacts and should be used to validate grouped changes. Do not publish a new tag for every small UI copy or layout change; publish when there is a useful feature or test batch for phone-side validation.

Native Roadmap

To converge with the upstream mobile design, the next implementation should add native Android modules in this order:

richer native layouts for kanban, group messages, timeline, and preferences
TerminalCore with ANSI parsing, cursor state, colors, and dirty rows
configurable shortcut bar backed directly by WebSocket input

4.7 KiB Raw Blame History