# Vectrum Code for Android

A companion app for [Vectrum Code](../README.md): the desktop's projects and threads on a phone,
in the desktop's look and themes. It's a remote client like another desktop: threads run on
the computer, with its agents, files, terminals and devices.

## Pairing

On the computer, open Settings → Connections and turn on **Allow remote connections**. Then, on
the phone, scan the QR code shown under **Pairing code**, or paste the code
(`192.168.2.10:47823,100.101.1.2:47823/<key>`: every address the computer listens on, and its
key). A `vectrum://…` link pairs too. The phone tries the addresses fastest first (the LAN, then
Tailscale, then another VPN), keeps the ones the computer reports as it moves between
networks, and falls back on the next one when an address doesn't answer. Several computers can be paired;
their threads share the sidebar, tagged with each one's name. The connection isn't encrypted,
so pair on networks you trust or over a VPN such as Tailscale or WireGuard.

## What it has

- The sidebar's inbox: pinned and active threads, the Working, Snoozed and Settled shelves,
  search, the project filter, and the thread menu on a long press (pin, settle, snooze, wake,
  rename, copy, delete) with the desktop's undo notices.
- The transcript: Markdown, tool calls folded into **Worked for** rows, subagents, plans,
  questions, the changed-files card and the diff view.
- The composer: model, reasoning and access pickers from the computer's agents, attachments,
  the `/` menu, steering and queueing, and the dock for approvals, questions, plans, queued
  messages, background tasks, usage limits and the task list.
- New threads on any paired computer's projects, in the current checkout or a new worktree,
  and adding projects (a folder there, a new one, or a clone).
- Settings: the computer's environment settings (with project overrides), Appearance with every
  theme family, Providers, Source Control, Connections, Archive and About.
- The right panel: subagents, terminals (shells on the computer, in the thread's folder, with
  an extra-keys row) and the Device panel (the computer's emulators and simulators, streamed
  and controlled from the phone).

Left out because the remote connection doesn't carry them: the browser panel, usage reports,
`@` file mentions, editing providers and starring models.

## Build

```sh
./gradlew :app:assembleDebug        # app/build/outputs/apk/debug/app-debug.apk
./gradlew :app:testDebugUnitTest
```

JDK 21 and the Android SDK (platform 37) are needed; point `local.properties` at the SDK
(`sdk.dir=…`) or set `ANDROID_HOME`.

## Layout

- `net/`: the desktop's remote protocol (`Protocol.kt`, mirroring `src/remote/mod.rs`) and the
  WebSocket that keeps a host connected (`Connection.kt`).
- `data/`: the app's state as Compose state: paired hosts, their projects, threads and open
  transcripts (`AppState.kt`), and this phone's own preferences (`DevicePrefs.kt`).
- `theme/`: MetalUI. `Palette.kt` reads `assets/themes.json`, which the desktop exports
  (`cargo test export_android_themes -- --ignored`), so every theme matches it exactly;
  `Metal.kt` has the surfaces (raised, well, plate, with the desktop's layered shadows), caps,
  switches, LEDs, keycaps and engraved labels.
- `ui/`: `sidebar/`, `chat/` (header, transcript, Markdown), `composer/` (composer, pickers,
  dock, start screen), `diff/`, `settings/`, `pair/` (pairing, adding projects), `panels/`
  (right panel, subagents, command palette), `terminal/` and `device/`.
- `term/`: the terminal emulator the terminal panel draws.
- `scripts/lucide.py`: turns the desktop's Lucide icons into vector drawables (`icons.txt`
  lists the ones in use).