opencode-android

An Android client for the opencode server, built with Crux (shared Rust core + Kotlin shell) and Jetpack Compose.

Architecture

┌─────────────────────────────────────────────────┐
│  Shell (Kotlin / Jetpack Compose)               │
│  ┌─────────────┐  ┌──────────────────────────┐  │
│  │ Compose UI   │  │  HttpClient / SseClient  │  │
│  │ (3 screens)  │  │  (Ktor + OkHttp)         │  │
│  └──────┬───────┘  └────────────┬─────────────┘  │
│         │                       │                │
│    Event (bincode)        Effect (bincode)        │
│         │                       ▲                │
│  ┌──────▼───────────────────────┴────────────┐   │
│  │  Core (ViewModel) — FFI bridge            │   │
│  │  CoreFfi → NativeCoreFfi / PureCoreFfi    │   │
│  └───────────────────────────────────────────┘   │
└──────────┬──────────────────────────────────────┘
           │  JNI (bincode bytes)
┌──────────▼──────────────────────────────────────┐
│  Core (Rust / Crux)                              │
│  ┌────────┐  ┌─────────┐  ┌──────────┐          │
│  │  App   │  │  Model  │  │ Commands │          │
│  │ update │  │ state   │  │ effects  │          │
│  └────────┘  └─────────┘  └──────────┘          │
│  No side-effects — pure logic                   │
└─────────────────────────────────────────────────┘

Rust Core (shared/)

• app.rs — Crux App implementation: Event, Model, ViewModel, Effect, update(), view()
  • Basic-auth detection: probes /global/health without credentials; on 401 surfaces auth_required in the ViewModel and waits for the user to supply credentials. All subsequent requests carry Authorization: Basic <base64(user:pass)> (RFC 7617).
  • Crash log tracking: accepts CrashLog(String) events from the shell and exposes crash_log_count / latest_crash_log in the ViewModel.
• ffi.rs — BoltFFI export wrapping crux_core::bridge::Bridge
• bin/codegen.rs — Type generator (produces Kotlin types via facet-generate)

Kotlin Shell (app/)

• CrashLogger.kt — Installs as the global UncaughtExceptionHandler. Crashes are persisted to filesDir/crashes/ (max 10 reports, newest first) and logged to logcat. Reports survive process death and can be enumerated/exported/cleared.
• core/CoreFfi.kt — FFI interface + JNI bridge (loads libopencode.so)
• core/PureCoreFfi.kt — Pure-Kotlin fallback (mirrors Rust logic for dev without NDK), includes basic-auth detection matching the Rust core
• core/Core.kt — Android ViewModel bridge: sends events, processes effects, exposes StateFlow<ViewModel>, forwards crash logs
• core/HttpClient.kt — Executes Effect.Http via Ktor/OkHttp, returns HttpResult to core
• core/SseClient.kt — Subscribes to opencode SSE event stream; errors reported to CrashLogger
• ui/screens/ — Connect (with credential fields), Sessions, Chat screens (Jetpack Compose + Material 3)

Generated Types (generated/)

• Auto-generated Kotlin types matching the Rust core (Event, Effect, ViewModel, Request, etc.)
• Bincode serialization helpers (com.novi.bincode, com.novi.serde)

Building

Prerequisites

• Rust 1.90+ (with Android NDK targets for native builds)
• Android SDK (compile SDK 36, build-tools 36.0.0)
• JDK 17+

Generate Kotlin types

cd shared
cargo run --bin codegen --features codegen -- --language kotlin --output-dir ../generated

Build native library (requires NDK)

# Install Android targets
rustup target add aarch64-linux-android armv7-linux-androideabi x86_64-linux-android

# Build and pack with BoltFFI
boltffi pack android

Build the APK

./gradlew assembleDebug

The app works without the native library — PureCoreFfi provides a pure-Kotlin reimplementation of the core logic. When libopencode.so is present, NativeCoreFfi is used automatically.

Run tests

# Rust core tests
cd shared && cargo test

# Kotlin shell tests
./gradlew testDebugUnitTest

Basic Auth Detection

The opencode server uses HTTP Basic Auth when OPENCODE_SERVER_PASSWORD is set (username defaults to opencode). The client detects this automatically:

1. On Connect, the core probes GET /global/health without credentials
2. If the server responds 401, the core sets auth_required = true in the ViewModel
3. The UI shows username/password fields
4. The user enters credentials and taps Connect again
5. The core retries the probe with Authorization: Basic <base64(user:pass)>
6. On 200, the core marks authed = true and all subsequent requests (sessions, messages, send, SSE) carry the Authorization header
7. On 401 with credentials, the core shows "Invalid credentials"

Crash Logs

CrashLogger installs as the global Thread.UncaughtExceptionHandler in OpencodeApp.onCreate(). When a crash occurs:

• The stack trace is written to logcat (opencode-crash tag)
• A crash report file is persisted to filesDir/crashes/crash_<timestamp>.txt
• Reports are pruned to the 10 most recent
• Reports survive process death and can be accessed via CrashLogger.getReports()

The crash log count is displayed on the Connect screen.

API Coverage

The client connects to an opencode server and supports:

• Health check (GET /global/health) — with basic-auth detection
• Session list (GET /session)
• Create session (POST /session)
• Load messages (GET /session/{id}/message)
• Send message (POST /session/{id}/prompt_async)
• SSE events (GET /event) — live message streaming

Configuration

The default server URL is http://localhost:4096. Change it in the Connect screen. android:usesCleartextTraffic="true" is enabled for local development.