Android APK

A small companion app that shows the focus timer in a real Android Picture-in-Picture window, or as a floating overlay above other apps. It is not the whole product — it is a remote control for the timer already running on your device.

What it actually does #

The APK contains no application logic and no database access. It polls two endpoints on the server already running on your device and renders whatever they return:

Both live in server.mjs. Because every action is relayed to the web app rather than applied directly, the APK cannot change your data on its own — if no browser tab has /focus open, actions have nowhere to land.

Build it #

No Android SDK fits comfortably in Termux, so the build runs in CI. The workflow is .github/workflows/pip-apk.yml.

1. Trigger the workflow. It also runs automatically on any push touching pipapk/**.

   gh workflow run pip-apk.yml
   
   # watch it
   gh run watch "$(gh run list --workflow=pip-apk.yml --limit=1 --json databaseId -q '.[0].databaseId')"

2. Download the artifact. It is named isotope-pip-debug.

   gh run download --name isotope-pip-debug --dir ~/apk-out
   ls -l ~/apk-out/app-debug.apk

3. Install it. Either open the file in Android’s package installer, or use ADB if you have it paired.

   adb install -r ~/apk-out/app-debug.apk

   Android will warn about installing from an unknown source. That is expected for a debug build and not something the workflow can avoid.

Point it at your server #

The default is http://127.0.0.1:3000, which works when the APK and the server are on the same device — the normal Termux case. The URL is editable in the app: type a new one and press Save URL. It is stored in SharedPreferences under pipapk_settings/server_url.

To drive a server on another machine, use its LAN address:

http://10.0.0.5:3000

Permissions, and why each exists #

The manifest declares thirteen. Most are inherited from the reference project rather than genuinely needed by this build, which is worth knowing before you grant them.

Four declared permissions do nothing here. They should be removed from the manifest — a permission you do not use is one you cannot justify, and it makes the install prompt look worse than the app deserves.

Behaviour worth knowing #

The two poll rates are worth separating, because conflating them makes the app sound worse than it is. AUTO_POLL_MS = 5000 drives autoStartPoll, whose only job is to notice that a session has begun and launch the overlay (PipActivity.kt:57). It renders nothing. The timer lives in the overlay service, which polls every second while running.

So the one user-visible consequence of the 5 s figure is this: starting a focus session can take up to five seconds to pop the overlay. That is a reasonable trade — the alternative is six times the wake-ups on a loop that runs whenever the app is foregrounded, to make a window appear slightly sooner.

More importantly, the countdown does not depend on the poll rate at all. /api/pip/state returns completionAtMs, an absolute timestamp, and TimerState.displaySecondsNow() derives the display from completionAtMs − now on every 40 ms tick. So the digits are correct continuously, and a slow or missed poll shifts nothing on screen. Only a change made elsewhere — a pause from the web app, say — waits for the next poll.

What it cannot do #

• Work without the server. No server on 127.0.0.1:3000 means an offline badge and nothing else. It is a remote control, not a client.
• Work without a browser tab. Actions are relayed over SSE to the open /focus page. With no tab open they are accepted and dropped.
• Show anything but the timer. No tasks, no syllabus, no analytics, no community.
• Update itself. Debug-signed with no release channel, so every upgrade is a manual reinstall.
• Be distributed. No Play listing and no signing key. Build it yourself or download the CI artifact.

If it does not connect #

Related #