opencode-mobile/docs/prd.md

OpenCode Mobile — Product Requirements Document (PRD)

Audience: product, design, support, and any engineer onboarding to the app. For implementation/architecture details, see tdd.md.

1. Product Vision

OpenCode Mobile is a phone-first companion for the OpenCode coding agent. It lets a developer keep an agent running on a powerful machine (laptop, cloud VM, Tailscale host) and stay in the loop from anywhere — review what the agent is doing, approve permissions, answer follow-up questions, and kick off new tasks — without needing to be at the keyboard.

The phone is not where heavy coding happens. The phone is where continuity happens: catching a long-running task at the right moment, unblocking it, and resuming work later from a real workstation.

2. Target Users

User	Why they use the app
Solo dev with a home dev box / cloud VM	Trigger or babysit long jobs while away from the laptop (commute, errands, meetings).
Devs working over Tailscale / Cloudflare Tunnel	Need a secure way to reach a private server from a phone.
Power users who run multiple agents	Want one place to monitor several servers and switch between them.

Out of scope: writing code on the phone full-time, replacing the desktop IDE, mass-collaboration features.

3. Core User Stories

3.1 Connect to a server

• As a user, I add a server by URL (https://host:port), optionally with HTTP basic-auth credentials, and the app stores them in the OS keychain.
• I can save multiple connections (local network, Tailscale, tunnel, cloud) and switch between them.
• If a connection fails, I get a plain-English diagnosis (not "Network request failed"), and a one-tap Share report that I can email or paste into Slack.

3.2 Authenticate

• On launch, the app can require Face ID / Touch ID / device biometrics before showing any sessions (opt-in, per-device setting).
• Sending a message can require an additional biometric confirmation (opt-in, for high-stakes setups).

3.3 Browse sessions

• The Sessions tab lists all sessions on the active connection, newest first, with title and a busy/idle indicator.
• Tapping a session opens its chat history; old messages load on scroll-up.

3.4 Chat with the agent

• New messages stream in over SSE in real time, including reasoning, tool calls, and final answers.
• Markdown is rendered with code blocks that have a one-tap Copy button.
• A status pill ("Thinking…", "Running command…", "Searching codebase…") tells the user what the agent is doing right now.
• The user can send a new message; the app posts it fire-and-forget and waits for SSE events to confirm.
• The user can abort a running task.

3.5 Approve permissions / answer questions

• When the agent requests permission to run a tool (e.g. bash, edit), the user gets an in-app prompt and an OS push notification.
• When the agent asks the user a question (multi-choice or free-form), the user gets the same dual prompt.
• The user can approve, deny, or answer from anywhere — including a notification tap that deep-links into the relevant session.

3.6 Stay informed

• Notifications cover: task completed, permission asked, question asked, session error, prolonged disconnect.
• Each notification category can be toggled in Settings.
• A tap on any notification opens the right session.

3.7 Recover from failures

• If the network drops, SSE reconnects with exponential backoff and jitter.
• If a render crash happens, the user sees a diagnostic screen (not a white screen / native red box) with the error, a Share Report button, and a Try Again button.
• Unexpected errors anywhere in the app are reported to Sentry automatically (when telemetry is enabled at build time); expected errors (timeouts, biometric-cancelled, etc.) are not — to keep signal high.

4. Non-Functional Requirements

• Privacy. URLs that contain credentials (basic-auth or ?token=…) are scrubbed before they leave the device. No PII in default Sentry payloads. No content of chat messages is uploaded.
• Offline-first diagnostics. Even with no internet, the user can share a full report via the OS share sheet (clipboard + native share).
• No required cloud dependency. The app talks only to the user's own OpenCode server. Sentry is opt-in via build-time env var and a hard no-op when absent.
• Battery / data. No background polling; SSE only when the app is in the foreground or actively used. Reconnect backoff caps at 15s.
• Security. Credentials live in Keychain/Keystore via expo-secure-store. Optional biometric gate. Cleartext HTTP is allowed on Android only because users frequently hit http://192.168.x.x:4096 on their own LAN.

5. Developer Workflow

See tdd.md for architecture details; this section covers the day-to-day workflow.

5.1 Local dev

npm install
npx expo start          # Metro bundler, scan QR with Expo Go
npx expo run:android    # build + install dev client on emulator/device
npx expo run:ios        # macOS only

5.2 Required env (optional but recommended)

Var	Purpose	Where
EXPO_PUBLIC_SENTRY_DSN	Enables crash reporting; absent → telemetry is a no-op	.env (local) + Bitwarden + GitHub Actions secret
SENTRY_AUTH_TOKEN	sentry-cli source-map upload during build	Bitwarden + GitHub Actions
SENTRY_ORG / SENTRY_PROJECT	sentry-cli release tagging	Bitwarden + GitHub Actions

All secrets are stored in Bitwarden under folder opencode-mobile. See AGENTS.md for retrieval commands.

5.3 Type / lint

npm run typecheck   # strict TypeScript, must pass before merge

5.4 Release

# 1. Bump app.json expo.version
# 2. Commit: "release: vX.Y.Z"
# 3. Tag and push:
git tag vX.Y.Z
git push origin main --tags
# CI (.github/workflows/build.yml) builds APK + GitHub Release

5.5 Observability

• Sentry dashboard: sentry.io → vibetechnologies → opencode-mobile
• Alert email: configure issue alert rules on the Sentry project to send to dzianisvv@gmail.com (or your distribution list).
• In-app log buffer: the last 200 log lines are always available in any shared diagnostic report; users can reproduce a bug and immediately share the trace.

6. Success Metrics

• P0 — Crash-free sessions: ≥ 99.5 % (Sentry sessions). Any release that drops below 99 % requires a hotfix.
• P1 — Connection diagnostic helpfulness: support requests for "Connection Failed" → 0 generic complaints; all reports come with a classification (tls-error, timeout, no-internet, etc.).
• P2 — Reconnect recovery: when the network blips for < 30 s, the user notices via a small banner but does not lose state.
• P3 — Notification latency: ≤ 5 s from agent event → push notification on the device.

7. Out of Scope (v0.x)

• Editing files on the phone.
• Running OpenCode locally on the device.
• Multi-user / shared sessions.
• Voice input beyond what the OS dictation keyboard provides.
• iPad / tablet-optimised layout (phone-first only; tablet works but is not designed for).