tmux/tmux-browser-android
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 10 Wiki Activity
main
tmux-browser-android/docs/android-client-notes.md
Codex dd056c8027
All checks were successful
Gitea Smoke / smoke (push) Successful in 0s
Details
Gitea Android APK / build (push) Successful in 12m19s
Details
Add projects page and smooth terminal input
2026-07-06 18:49:28 +00:00

4.9 KiB
Raw Permalink Blame History

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, Projects, 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 Projects page for kanban project grouping, project agents, project messages, add/remove session, create, and delete actions
  • native Tools page for health, server status, timeline, preferences, 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 settings, app version/build type, package name, selected update source, and HTTP/WebSocket 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:

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