# ai-app

A phone interface to AI coding sessions (Claude Code and llama.cpp via pi),
replacing the Claude app for daily use. Rust/Axum backend on the desktop,
Kotlin/Compose Android app, WireGuard + pinned self-signed TLS + bearer token
between them.

**`PLAN.md` is the design source of truth.** Read it before building or
changing anything structural. It records every decision with its date, its
rationale, and the alternatives that were rejected and why — keep that habit
when a decision changes: update the plan in place, don't let this file and
the plan drift into two versions of the truth. This file is the working notes
layer: conventions, commands, and things that have bitten.

The central design point, worth not undoing by accident: **a session is a
child process speaking JSONL over stdio, translated into one common event
model.** Claude Code (stream-json) and pi (RPC mode) are two translators
behind one `Driver` trait; the transcript, the SSE stream, the phone UI, and
SSH spawning (the same command wrapped in `ssh host …`) all work purely in
the common model. A new session type is a new driver — never a
session-type branch in shared code (routes, transcript, app screens).

## Layout

Mirrors `../local-updater` deliberately — same stack (axum 0.8 +
axum-server/rustls, tokio, clap; Kotlin 2.4.x + Compose Multiplatform,
single `:androidApp` module), same cert scheme, same registry pattern (every
session mutation funnels through the manager so in-memory and on-disk state
can't come apart). Read local-updater's `README.md` and `AGENTS.md` for the
conventions before diverging from them; module-by-module intent for this
repo is in PLAN.md's "Backend layout" section.

- `server/` — Rust backend (to be created, phase 1).
- `app/` — Compose Android app (to be created, phase 1).
- `gen-dev-cert.sh` / `certs/` — copied from local-updater's scheme
  (idempotent CA, reissued leaf; regenerating the CA strands the installed
  app — same one-way door).

## Status

Pre-implementation. Phases are in PLAN.md; phase 1 (Skeleton) proves the
whole pipe — TLS, token auth, wg0-bound listener, SSE with transcript
cursors, both app screens — against a fake `EchoDriver` before any AI is
involved. Every phase ends runnable and verified against the real thing.

## Checking your work

Fill in real commands as they're created; until then, the inherited posture:

- Server: `cargo test` + `cargo clippy --all-targets` from `server/` —
  the build stays warning-clean from the first commit.
- App: from `app/`, `. ./android-env.sh && ./gradlew :androidApp:compileDebugKotlin`.
- Tests where logic is pure (event normalization, transcript cursors, config
  persistence, llama-server refcounting); the app is UI over the API and is
  verified by running it.
- Prefer exercising the server directly over going through the UI:
  `curl --cacert certs/ca.pem -H "Authorization: Bearer …" https://…`.

## Environment notes (this machine, learned in local-updater)

- Android SDK is at `~/Android/Sdk`, not the root-owned `/opt/android-sdk`
  the ambient `$ANDROID_HOME` may point at; copy local-updater's
  `android-env.sh` override pattern.
- Each agent command runs in a fresh shell — exported environment does not
  carry over. Chain: `cd app && . ./android-env.sh && ./gradlew …`. Never
  pipe `source` into `head`/`grep` (subshell discards the exports).
- The shared emulator AVD is named `tdep` — one emulator across the Android
  projects on this machine, not one per repo.
- Long-running servers launched from an agent must be fully detached
  (`setsid nohup … & disown -h`, verify `PPID 1`), and every
  `pgrep -f`/`pkill -f` pattern needs its first character bracketed
  (`[a]i-server`) in **every** occurrence in the command, or the pattern
  matches the shell running it. Full explanation in local-updater's
  `AGENTS.md` — it bites exactly the same way here.