Skip to content

About

Mobile PWA client for your opencode server: streaming chat, permissions, model picker and file attach (no frameworks)

Topics

Resources

Code of conduct

Contributing

Security policy

Accessibility

Stars

2 stars

Watchers

1 watching

Forks

OpenCode Móvil — PWA client for opencode

⚠️ Disclaimer / Aviso: this is an unofficial, community-made project. It is not built by the OpenCode team and is not affiliated with or endorsed by opencode or Anomaly in any way. «opencode» is used only to describe what this app connects to.

Este es un proyecto no oficial hecho por la comunidad. No está desarrollado por el equipo de OpenCode ni está afiliado ni respaldado por opencode o Anomaly.

License: MIT No frameworks App dependencies CI Tests PWA GitHub stars

▶️ Try the live demo — fake data, nothing to install.

Animated demo: session list, search, chat with permissions and model picker

Sessions list with search and sort Chat with permissions banner, Plan/Build switch and model picker Approve or reject agent permissionsSettings: theme, language, security and notifications

A mobile Progressive Web App to drive your opencode server from your phone: chat with your sessions in real time, approve permissions, pick the model, browse your project's files and attach them, all from a tiny, dependency-free client.

Español: Ir a la versión en español

▶️ Prueba la demo — datos ficticios, sin instalar nada.

Demo animada: lista de sesiones, búsqueda, chat con permisos y selector de modelo

Lista de sesiones con buscador y orden Chat con banner de permisos, Plan/Build y selector de modelo Aprobar o rechazar permisos del agente Ajustes: tema, idioma, seguridad y notificaciones


✨ Features

  • Real-time chat with streaming responses (SSE), reasoning, tool chips and a stop button.
  • Search inside a conversation (highlight + jump between matches) and copy the whole chat as Markdown.
  • Session list with search, sorting and project filter (recent / oldest / name; the project filter appears only when you have more than one project).
  • System view: MCP servers (connect/disconnect), model providers, plugins, skills and commands.
  • Multilingual UI (Spanish / English / German), auto-detected from your browser — add your language.
  • Resilient connection: the event stream reconnects with exponential back-off (1 s → 30 s + jitter).
  • Permission control: approve or reject what the agent asks for (once / always / reject), right from your phone. Live banner in the chat, badge counter in the session list and a dedicated screen.
  • Plan / Build mode switch: flip the agent's mode with one tap.
  • Model + variant picker: 130+ models from all your providers, with search and per-model reasoning variants (low…max).
  • Attach files from the PC: browse your project folders and reference files in your prompt.
  • Security: strict CSP in production, PIN lock (PBKDF2, brute-force cooldown, auto-lock on inactivity), QR token scrubbing from the URL, "log out" button.
  • Light / dark / auto theme, following your system.
  • Keyboard shortcuts (desktop): Ctrl/Cmd+K to search, Enter to send, Shift+Enter for a line break, Esc to close.
  • Local notifications when the agent needs a permission while you are not looking at the app.
  • Real push notifications (Web Push / VAPID): they arrive with the app closed. Includes a tiny push service (server/push-server.mjs) you run next to opencode — no third party involved.
  • No frameworks: vanilla JS + a ~20-line DOM helper. ~37 kB gzipped (JS + CSS).

📱 Platform support

Feature Android iOS (iPhone/iPad) Desktop
Chat, sessions, permissions, model picker, attach files ✅ ✅ ✅
PIN lock (needs HTTPS) ✅ ✅ ✅
Install as an app ✅ ✅ (Share → Add to Home Screen) ✅ (Chrome/Edge)
In-app alerts (badge 🛡, chat banner) ✅ ✅ ✅
System notification when the app is closed (local, ~30 s) ✅ ⚠️ only if installed + no background wake ✅
Real push with the app closed (own service) ✅ ⚠️ only if installed (iOS 16.4+) ✅

Notes

  • iOS: Apple only allows web apps installed on the Home Screen to notify (since iOS 16.4). Even then, iOS does not allow waking the app in the background, so a local notification only arrives shortly after you leave the app. The app detects this and tells you what to do. Also: iOS does not run the PIN over plain http:// (needs HTTPS) — use the tunnel.
  • Windows / macOS / Linux as the server: the file browser works with either path separator, so attaching files works with an opencode server on any OS.
  • Notifications come in two layers. Local ones work with nothing else, but only for ~30 s after you hide the app. Real push arrives with the app closed and needs the bundled service server/push-server.mjs running next to opencode (see below).

🔔 Real push notifications (app closed)

Local notifications can only fire while something of the app is still running. To notify with the app closed you need Web Push: the browser keeps a channel with its push service (FCM/APNs/Mozilla) and a server of your own wakes it. That server ships with the app and runs on your PC.

# 1) service dependency (once)
npm i web-push

# 2) start the service (generates the VAPID keys the first time)
node server/push-server.mjs

Then, in the app: Settings → Push notifications, set the service URL and hit Enable push.

  • Same machine: http://127.0.0.1:8099
  • From your phone: the https tunnel URL you use for the app, with /push appended (Vite proxies it to the service, so no extra port is exposed).

The VAPID keys and the subscriptions live in ~/.opencode-mobile/ (never in the repo). The service authenticates with your opencode password, so it only answers to whoever already controls opencode.

Without the push service notifications still work in their local version; the app explains this in Settings instead of failing silently.

  • opencode desktop or CLI installed and running on your PC (the server listens on 127.0.0.1:28894).
  • Node.js 18+ to build and serve the PWA.

🚀 Quick start

Just want to look? → live demo (fake data, no install).

Want to use it for real? You need an opencode server running on your PC:

git clone <this-repo>
cd opencode-mobile
npm install

# Development (hot reload), reachable from your LAN:
npm run dev            # http://localhost:5173

# Just want to see the UI? Prebuilt demo with fake data, no opencode needed:
npm run demo           # http://localhost:4174

# Production build + serve (with the /api proxy the app needs):
npm run build
npm run preview        # http://localhost:4173

# Unit tests (no dependencies, uses Node's built-in runner):
npm test

Then open the app and connect:

# Generate a QR with a 30-day token and scan it with your phone:
node scripts/qr-pairing.mjs http://<your-lan-ip>:5173

HTTPS access from the phone (recommended)

Some features (PIN lock, service worker, notifications) require a secure context. http://localhost counts, but a LAN IP does not. To get real HTTPS:

# Windows
pwsh scripts/movil.ps1
# macOS / Linux
bash scripts/movil.sh

It starts the preview, opens a Cloudflare quick tunnel and generates a QR pointing to the HTTPS URL. Requires cloudflared.

🧠 How it connects

The opencode API only allows CORS from loopback, so the PWA talks to /api on its own origin and the Vite dev/preview server proxies it to 127.0.0.1:28894 (see vite.config.js). This makes it work identically on localhost, on your LAN and through the tunnel.

🔒 Security notes

  • The server password is never written to disk in the repo; the QR script reads it from the opencode CLI in memory.
  • A QR contains a 30-day token (equivalent to the password). Treat it as a secret.
  • The app stores the credential in the phone's localStorage.
  • PIN lock is local to the device (PBKDF2-SHA256, 150k iterations, per-failure back-off).

🗂 Project layout

opencode-mobile/
├── index.html
├── vite.config.js          # base path, /api proxy, strict CSP for production builds
├── public/                 # manifest, service worker, icons
├── scripts/
│   ├── qr-pairing.mjs      # generate the access QR (cross-platform)
│   ├── movil.ps1 / movil.sh # one-shot: preview + cloudflare tunnel + QR
│   ├── recortar-captura.ps1 # crop screenshots to phone size
│   └── generar_iconos.ps1
├── test/
│   └── unit.test.js        # unit tests (Node's built-in runner)
├── server/
│   └── push-server.mjs     # Web Push service (run next to opencode)
└── src/
    ├── main.js             # bootstrap, routes, theme, lock
    ├── api/client.js       # HTTP + SSE client
    ├── security.js         # PIN (PBKDF2), inactivity lock
    ├── theme.js            # light/dark/auto
    ├── notify.js           # local notifications
    ├── push.js             # Web Push subscription (VAPID)
    ├── permisos-avisos.js  # background permission watcher
    ├── ui/                 # dom.js, router.js, chat-controls.js, atajos.js
    └── views/              # setup, sessions, chat, permissions, settings

🧪 Tests

35 unit tests cover the logic without a DOM: markdown rendering (safe escaping, code blocks, lists), timeAgo, the path utilities of the file browser (which must work against an opencode server on Windows, macOS and Linux), the session filter (project / text / sort) and i18n (every dictionary must have the same keys as the reference one, with its {x} placeholders intact). They use Node's built-in test runner, so they add no dependencies:

npm test

About "zero dependencies": the app itself ships no runtime dependency — it's vanilla JS you can read in one sitting. The only entry in package.json is web-push, and it's used exclusively by the optional push service (server/push-server.mjs), which runs on your PC, not in the browser.

🤝 Contributing

**Everyone is welcome!**This is a small, framework-free project — easy to read and easy to hack on.

  • 🟢 New here? Check the pinned issues 👋 Ideas para colaborar (easy tasks) and the 🗺️ Roadmap.
  • ⚡ Start in 2 minutes: npm install && npm run demo — fake data, no opencode server needed. Perfect for UI, CSS, accessibility and translation work.
  • 📖 Read CONTRIBUTING.md for the setup and the two hard design rules (no UI framework, no inline scripts/styles).
  • 🏅 Every merged contribution gets your name in CONTRIBUTORS.md and a mention in the release notes.
  • 🐛 Found a bug? Open an issue — there is a template for it.
  • 💡 Have an idea? Use the Feature request template (explain the problem first).
  • 🔒 Security problem? Do not open a public issue — see SECURITY.md.
  • ♿ Accessibility barrier? See ACCESSIBILITY.md — what is done, what is limited, and how to report it.

No contribution is too small: a typo fix, a translation, a screenshot or a bug report all help. If you are unsure, open a Discussion and ask. 🙌

📄 License

MIT — see LICENSE.


🇪🇸 Español

Un cliente PWA para móvil que te permite manejar tu servidor opencode desde el teléfono: chatear con tus sesiones en tiempo real, aprobar permisos, elegir el modelo, explorar los archivos de tu proyecto y adjuntarlos, todo con un cliente pequeño y sin dependencias.

✨ Qué hace

  • Chat en tiempo real con respuestas en streaming (SSE), razonamiento, chips de herramientas y botón de detener.
  • Buscar dentro de la conversación (resalta y salta entre coincidencias) y copiar todo el chat en Markdown.
  • Lista de sesiones con buscador, orden y filtro por proyecto (recientes / antiguas / nombre; el filtro por proyecto aparece solo si tienes más de uno).
  • Vista Sistema: servidores MCP (conectar/desconectar), proveedores de modelos, plugins, skills y comandos.
  • Interfaz multiidioma (español / inglés / alemán), detectada automáticamente del navegador — añade tu idioma.
  • Conexión resistente: el stream se reconecta con backoff exponencial (1 s → 30 s + jitter).
  • Control de permisos: aprueba o rechaza lo que pide el agente (una vez / siempre / rechazar) desde el móvil. Banner en vivo en el chat, contador en la lista de sesiones y pantalla propia.
  • Conmutador Plan / Build: cambia el modo del agente con un toque.
  • Selector de modelo y variante: más de 130 modelos de todos tus proveedores, con buscador y variantes de razonamiento (low…max).
  • Adjuntar archivos del PC: navega por las carpetas de tu proyecto y referéncialos en el mensaje.
  • Seguridad: CSP estricta en producción, bloqueo con PIN (PBKDF2, cooldown antifuerza bruta, cierre por inactividad), borrado del token del QR en la URL y botón de cerrar sesión.
  • Tema claro / oscuro / automático, siguiendo al sistema.
  • Atajos de teclado (escritorio): Ctrl/Cmd+K para buscar, Enter para enviar, Shift+Enter para salto de línea y Esc para cerrar.
  • Notificaciones locales cuando el agente pide un permiso y no estás mirando la app.
  • Notificaciones push reales (Web Push / VAPID): llegan con la app cerrada. Incluye un servicio push mínimo (server/push-server.mjs) que corres junto a opencode, sin depender de terceros.
  • Sin frameworks: JS vanilla + un helper DOM de ~20 líneas. Unos 37 kB comprimidos (JS + CSS).

📱 Compatibilidad de plataformas

Función Android iOS (iPhone/iPad) Escritorio
Chat, sesiones, permisos, modelo, adjuntar archivos ✅ ✅ ✅
PIN (necesita HTTPS) ✅ ✅ ✅
Instalar como app ✅ ✅ (Compartir → Añadir a pantalla de inicio) ✅ (Chrome/Edge)
Avisos en la app (badge 🛡, banner del chat) ✅ ✅ ✅
Notificación del sistema con la app cerrada (local, ~30 s) ✅ ⚠️ solo si está instalada + sin despertar en 2º plano ✅
Push real con la app cerrada (servicio propio) ✅ ⚠️ solo si está instalada (iOS 16.4+) ✅

Notas

  • iOS: Apple solo permite notificar a las webs instaladas en la pantalla de inicio (desde iOS 16.4). Y aun así, iOS no permite despertar la app en segundo plano, así que el aviso local llega solo si acabas de salir de la app. La app lo detecta y te dice qué hacer. Además, en iOS el PIN no funciona por http:// (necesita HTTPS): usa el túnel.
  • Servidor en Windows / macOS / Linux: el explorador de archivos funciona con cualquier separador de ruta, así que adjuntar archivos va con el servidor opencode en cualquier sistema.
  • Notificaciones: hay dos capas. Las locales funcionan sin nada más, pero solo durante los ~30 s siguientes a ocultar la app. Las push reales llegan con la app cerrada y necesitan el servicio server/push-server.mjs corriendo junto a opencode (ver más abajo).

🔔 Notificaciones push reales (app cerrada)

Las notificaciones locales solo pueden dispararse mientras algo de la app siga corriendo. Para avisar con la app cerrada hace falta Web Push: el navegador mantiene un canal con su servicio push (FCM/APNs/Mozilla) y un servicio propio lo despierta. Ese servicio viene incluido y corre en tu PC.

# 1) dependencia del servicio (una vez)
npm i web-push

# 2) arranca el servicio (genera las claves VAPID la primera vez)
node server/push-server.mjs

Luego, en la app: Ajustes → Notificaciones push, pon la URL del servicio y pulsa Activar push.

  • Misma máquina: http://127.0.0.1:8099
  • Desde el móvil: la URL del túnel https que uses para la app, con /push al final (Vite lo proxya al servicio; no hace falta abrir otro puerto).

Las claves VAPID y las suscripciones se guardan en ~/.opencode-mobile/ (nunca en el repositorio). El servicio se autentica con la misma contraseña de tu opencode, así que solo responde a quien ya controla opencode.

Sin servicio push las notificaciones siguen funcionando en su versión local; la app te lo explica en Ajustes en vez de fallar en silencio.

🔧 Requisitos

  • opencode instalado y en marcha en tu PC (el servidor escucha en 127.0.0.1:28894).
  • Node.js 18+ para compilar y servir la PWA.

🚀 Puesta en marcha

¿Solo quieres verla? → demo (datos ficticios, sin instalar).

¿Quieres usarla de verdad? Necesitas un servidor opencode en tu PC:

git clone <este-repo>
cd opencode-mobile
npm install

npm run dev            # desarrollo, accesible desde tu LAN (http://localhost:5173)
npm run demo           # ver la UI con datos falsos, SIN servidor opencode (:4174)
npm run build          # build de producción
npm run preview        # sirve el build con el proxy /api (http://localhost:4173)
npm test               # tests unitarios (runner nativo de Node, sin dependencias)

Luego genera el QR y escanéalo desde el móvil:

node scripts/qr-pairing.mjs http://<ip-de-tu-pc>:5173

Acceso por HTTPS desde el móvil (recomendado)

Algunas funciones (PIN, service worker, notificaciones) necesitan un contexto seguro. http://localhost lo es, pero una IP de LAN no. Para tener HTTPS de verdad:

pwsh scripts/movil.ps1     # Windows
bash scripts/movil.sh      # macOS / Linux

Arranca la preview, abre un túnel rápido de Cloudflare y genera un QR apuntando a la URL HTTPS. Requiere cloudflared.

🧠 Cómo se conecta

La API de opencode solo permite CORS desde loopback, así que la PWA habla con /api en su propio origen y el servidor de Vite lo reenvía a 127.0.0.1:28894 (ver vite.config.js). Así funciona igual en localhost, en tu LAN y a través del túnel.

🔒 Notas de seguridad

  • La contraseña del servidor nunca se guarda en disco dentro del repo; el script del QR la lee del CLI de opencode solo en memoria.
  • Un QR contiene un token de 30 días (equivalente a la contraseña). Trátalo como un secreto.
  • La app guarda la credencial en el localStorage del móvil.
  • El PIN es local al dispositivo (PBKDF2-SHA256, 150k iteraciones, espera creciente por fallo).

🧪 Tests

35 pruebas cubren la lógica sin DOM: el render de markdown (escape seguro, bloques de código, listas), timeAgo, las utilidades de rutas del explorador (deben funcionar con el servidor opencode en Windows, macOS y Linux), el filtro de sesiones (proyecto / texto / orden) y la i18n (cada diccionario debe tener las mismas claves que el de referencia y conservar sus marcadores {x}). Usan el runner nativo de Node: no añaden dependencias.

npm test

Sobre lo de "sin dependencias": la app no tiene ninguna dependencia de ejecución — es JS vanilla que se lee de una sentada. La única entrada en package.json es web-push, y la usa exclusivamente el servicio de push opcional (server/push-server.mjs), que corre en tu PC, no en el navegador.

🤝 Cómo colaborar

¡Cualquiera es bienvenido! Es un proyecto pequeño y sin frameworks: fácil de leer y fácil de tocar.

  • 🟢 ¿Nuevo por aquí? Mira los issues fijados 👋 Ideas para colaborar (tareas fáciles) y el 🗺️ Roadmap.
  • ⚡ Empieza en 2 minutos: npm install && npm run demo — datos falsos, sin servidor opencode. Perfecto para trabajar en UI, CSS, accesibilidad y traducciones.
  • 📖 Lee CONTRIBUTING.md para el setup y las dos reglas de diseño (sin framework de UI, sin scripts/estilos en línea).
  • 🏅 Cada contribución mezclada lleva tu nombre en CONTRIBUTORS.md y una mención en las notas de la versión.
  • 🐛 ¿Un fallo? Abre un issue (hay plantilla).
  • 💡 ¿Una idea? Usa la plantilla Feature request (explica el problema antes).
  • 🔒 ¿Problema de seguridad? No abras un issue público — mira SECURITY.md.
  • ♿ ¿Una barrera de accesibilidad? Mira ACCESSIBILITY.md: qué se hace, qué está limitado y cómo reportarlo.

Ninguna aportación es pequeña: corregir una errata, traducir, una captura o reportar un bug ayudan. Si dudas, abre una Discussion y pregunta. 🙌

📄 Licencia

MIT — ver LICENSE.

About

Mobile PWA client for your opencode server: streaming chat, permissions, model picker and file attach (no frameworks)

Topics

Resources

Code of conduct

Contributing

Security policy

Accessibility

Stars

2 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages