OpenCode Mobile Client

An iPhone-first mobile shell for OpenCode, designed for useful daily mobile use and shipped in small, ready-to-use releases.

Release baseline

The current release baseline is v1.7.2, and the shipped package.json version 1.7.2 now matches that release.

Phase 14 reconciled older duplicate release docs, release-proof workflow state, and browser-validation commands around that baseline. Treat .opencode/plans/current-phase.md and docs/releases/phase-registry.md as the authoritative workflow surfaces.

The running app is still a local-first mobile shell with mock-backed local task replies, file viewing, diff review, installability, and offline-aware shell behavior.

The latest shipped v1.7.2 release aligns the browser-proof command surfaces with the real repo-root runner and proof flow while preserving the app's honest local-first product scope.

Current product reality

This repository currently ships a local-first mobile shell, not a live backend client.

• sessions and shell state persist on the current device
• local sessions still use mock-backed task replies, file views, and diff review for mobile workflow validation
• remote-marked sessions no longer invent a final local assistant success while a remote run is active; they wait for backend-owned completion output or show an explicit missing or failed state
• online and offline indicators reflect browser connectivity and install or reload conditions, not a live OpenCode session
• the product is being delivered in small phases before any real transport or authentication work exists

Product direction

This project is a mobile-first OpenCode shell optimized for:

• one-handed iPhone use
• readable long-running agent output
• compact task execution on narrow screens
• staged delivery through small release phases
• PWA-first deployment with room for a later native wrapper if justified

How to run the project right now

Quick local development

1. Install dependencies:
   • npm install
2. Start the Vite dev server:
   • npm run dev
3. Open the local URL printed by Vite in your terminal.

Use this path when you want the fastest edit-and-refresh loop on the same machine.

Exact repo validation and preview flow

This is the current repo-owned path used before phone testing and release-proof work:

1. Install dependencies:
   • npm install
2. Run the combined local gate:
   • npm run validate:local
3. Start the preview server on the fixed phone-testing port:
   • npm run preview:host
4. Open:
   • http://127.0.0.1:4173/

npm run validate:local runs workflow:check, lint, test, and build. npm run preview:host serves the built app on 0.0.0.0:4173.

Phone access guide: Tailscale or Cloudflare

Option 1: open it with your Tailscale IP

1. On the machine running this repo, get the Tailscale IP:
   • tailscale ip -4
2. Build and start the preview server:
   • npm run validate:local
   • npm run preview:host
3. On your phone, while connected to the same tailnet, open:
   • http://<your-tailscale-ip>:4173/

If you use a Tailscale MagicDNS hostname instead of the raw IP, allow it explicitly when starting preview:

• OPENCODE_ALLOWED_HOSTS=your-machine.your-tailnet.ts.net npm run preview:host

Option 2: create a Cloudflare URL

1. Install cloudflared separately if it is not already available on your machine.
2. In one terminal, build and start preview:
   • npm run validate:local
   • npm run preview:host
3. In a second terminal, start a tunnel to the preview server:
   • cloudflared tunnel --url http://127.0.0.1:4173
4. Open the generated https://...trycloudflare.com URL on your phone.

If you later bind a stable custom hostname to that tunnel, allow that hostname explicitly when starting preview:

• OPENCODE_ALLOWED_HOSTS=preview.example.com npm run preview:host

Working model

This repository is operated through OpenCode phase commands.

The normal workflow is:

1. /phase-status
2. /next-phase
3. /run-phase
4. /validate-phase
5. /ship-phase

Use npm run repo:doctor before starting a new phase when you want a fast health check for release-state truth, clean-install reproducibility, and workflow-file presence.

Preview host configuration

npm run preview:host keeps the existing localhost and 127.0.0.1 behavior by default.

If you need to open the preview from a phone through a LAN, Tailscale MagicDNS, Cloudflare-backed custom hostname, or other named host, set OPENCODE_ALLOWED_HOSTS explicitly instead of editing vite.config.js for one machine.

Examples:

• OPENCODE_ALLOWED_HOSTS=phone-preview.example.ts.net npm run preview:host
• OPENCODE_ALLOWED_HOSTS=phone-preview.example.ts.net,second-host.local npm run preview:host

Leave OPENCODE_ALLOWED_HOSTS unset when you only need the default local preview path.

Delivery rules

• One phase at a time
• One release per phase
• Every phase must end in a usable state
• No hidden scope expansion
• Current phase state lives in .opencode/plans/current-phase.md
• Release tracking lives in docs/releases/phase-registry.md
• /ship-phase creates the release commit automatically
• /ship-phase pushes to origin main only when the current branch is already main

UX rules

• iPhone-first, portrait-first
• Safe-area-aware top and bottom surfaces
• No critical action hidden behind dense menus
• Thumb-friendly primary actions
• No desktop-style multi-panel layouts in early releases
• Prefer clarity over feature count

Repository structure

• AGENTS.md — project operating rules for OpenCode
• opencode.json — project-local OpenCode configuration
• .opencode/agents/ — workflow-specific agents
• .opencode/backlog/candidates.yaml — deterministic next-phase candidate list for post-release work
• .opencode/commands/ — slash commands for phase execution
• .opencode/plans/current-phase.md — authoritative current phase file
• docs/releases/ — release phases and registry