Clawdex Mobile

Control Clawdex from your phone using an Expo React Native app (apps/mobile) and a Rust bridge (services/rust-bridge) running on your host machine.

This project is intended for trusted/private networking (Tailscale or local LAN). Do not expose the bridge publicly.

What You Get

• Mobile chat with Clawdex
• Voice-to-text transcription (push-to-talk)
• Live run/activity updates over WebSocket
• Plan/default collaboration mode support
• Clarification and approval flows in-app
• File/image attachments from workspace and phone
• Chat-scoped Git actions (status/diff/commit/push)
• Bridge-backed terminal execution

Quick Start

Download Mobile App

• Android APK: download from the latest GitHub release assets
  https://github.com/Mohit-Patil/clawdex-mobile/releases/latest
• iOS (TestFlight): share your TestFlight invite/public link with testers (coming soon)

Recommended release-note format for Android:

• Android APK: <direct asset URL>
• SHA-256: <apk checksum>

Option A: Published CLI (recommended)

npm install -g clawdex-mobile@latest
clawdex init

This is the primary starting point.

clawdex init guides you through:

1. bridge mode selection: Local (LAN) or Tailscale
2. secure bridge config generation (.env.secure)
3. phone readiness checks for selected mode
4. optional bridge launch in the foreground (release build)

When the bridge starts, it prints a pairing QR:

• preferred: QR contains both bridgeUrl + bridgeToken (one-scan onboarding)
• fallback: token-only QR if host is not a phone-connectable address

Typical lifecycle:

# install/update once
npm install -g clawdex-mobile@latest

# onboarding + start bridge
clawdex init

# stop services later
clawdex stop

Option B: Monorepo checkout

npm install
npm run setup:wizard

Use npm run setup:wizard -- --no-start to configure only (no bridge start).

Project Layout

• apps/mobile: Expo client (UI + API client)
• services/rust-bridge: primary bridge (WebSocket JSON-RPC + codex app-server adapter)
• services/mac-bridge: legacy TypeScript bridge (reference only)
• scripts/: onboarding/runtime helper scripts
• docs/: setup, troubleshooting, architecture notes

Prerequisites

• macOS or Linux
• Node.js 20+
• npm 10+
• codex CLI in PATH
• git in PATH
• iOS app installed (TestFlight/App Store/dev build)
• Tailscale on host + phone (recommended for remote/private networking)

Optional for simulators/emulators:

• Xcode + iOS Simulator
• Android Studio + Android Emulator

Day-to-Day Commands

From repo root:

• npm run setup:wizard — guided secure setup + optional bridge start
• npm run stop:services — stop running bridge (and Expo if running)
• npm run secure:setup — generate/update secure env
• npm run secure:bridge — start rust bridge from .env.secure (release profile)
• npm run secure:bridge:dev — start rust bridge in dev profile
• npm run mobile — start Expo
• npm run ios — start Expo (iOS target)
• npm run android — start Expo (Android target)
• npm run teardown — interactive cleanup
• npm run lint / npm run typecheck / npm run build

Published CLI:

• clawdex init
• clawdex stop
• clawdex upgrade / clawdex update
• clawdex version

Bridge Start Flow

Recommended:

npm install -g clawdex-mobile@latest
clawdex init

Monorepo/manual flow:

# from repo root
npm install
npm run secure:setup
npm run secure:bridge

Keep npm run secure:bridge running in foreground. It prints pairing QR and bridge logs.

In a second terminal, start the app runtime:

npm run mobile

Onboarding In App

On first launch (or after reset):

1. choose mode (Local or Tailscale)
2. scan bridge QR to autofill URL + token
3. use Test Connection (health + authenticated RPC check)
4. tap Continue

EAS Builds (Short)

Run EAS commands from apps/mobile (that is where app.json and eas.json live):

cd apps/mobile
eas build --platform ios --profile preview
eas build --platform android --profile preview

For complete build/submit guidance, see docs/eas-builds.md.

Local Builds (No EAS Cloud)

Run from apps/mobile:

cd apps/mobile

iOS:

# iOS Simulator
npx expo run:ios

# Connected iPhone
npx expo run:ios --device

Android:

# Android emulator or connected Android device
npx expo run:android

Optional local EAS build:

# Requires local Android SDK / Xcode setup
eas build --platform android --profile preview --local

Documentation Map

• Setup + operations: docs/setup-and-operations.md
• Troubleshooting: docs/troubleshooting.md
• Realtime sync limits/mitigations: docs/realtime-streaming-limitations.md
• Voice transcription internals: docs/voice-transcription.md
• Open-source license obligations: docs/open-source-license-requirements.md
• App review template: docs/app-review-notes.md
• App-server/CLI gap tracking: docs/codex-app-server-cli-gap-tracker.md

Open Source License Requirements

Follow project requirements in:

• LICENSE
• docs/open-source-license-requirements.md

Development Checks

From repo root:

npm run lint
npm run typecheck
npm run build
npm run test