ai-app/AGENTS.md

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.