MobileCode

Phone-native AI Coding Harness
The agent harness runs on the phone. Models can be remote; the coding loop, files, previews, runtime routing, and shipping controls stay in MobileCode.
不是远程 IDE 的手机壳，而是真正把 agent loop、工具状态、文件、预览和发布控制面放到手机本机的 MobileCode。

Watch 15s Short · Watch 9:16 Promo Video · README Motion Cover · HTML Principle Video · Download v0.1.24 APK · GitHub Pages Demo

Demo Lab · 2048 Demo · GitHub Test · Download APK · Release QA

_{15-second Remotion teaser with voiceover. Full explainer covers demand, pain, RuntimeProvider, and GitHub-first shipping.}

Runs on the phone	Remote by choice	GitHub-first shipping
Agent trace, tool selection, runtime routing, local files, WebView preview, result cards	Model provider, optional Cloud Runtime, external Termux/Helper backends	Repo discovery, Contents API commits, Pages publish, Actions builds, release artifacts

Why MobileCode

MobileCode 的第一性原理很简单：手机端不适合塞一个完整桌面编译环境，但非常适合成为 AI coding 的本机 harness。

它不是 Codex Remote、Claude Remote 或云端 IDE 的移动端外壳。模型可以来自云端 provider，但对话、工具编排、运行时选择、文件落盘、WebView 预览、GitHub 发布和恢复提示都在手机 App 内闭环。

它把最重的部分交给外部平台，把最贴近用户的部分留在手机上：

Layer	MobileCode does	External layer does
Phone-native harness	Chat, tool trace, role cards, file cards, preview, runtime diagnostics, settings	None
Local runtime	Helper / Termux / WebViewOnly through RuntimeProvider	Shell, logs, small local tasks
GitHub-first workspace	Repo Hub, watchlist, remote-linked folders, Pages publish cards	Repos, Contents API commits, Actions builds, artifacts
Web artifacts	Generate HTML, run publish readiness checks, open browser/WebView	GitHub Pages hosting
Heavy builds	Show workflow status, jobs, artifacts	GitHub Actions APK/Web/release builds

Effect Showcase

These thumbnails are generated from the live GitHub Pages demos with just-thumbnail, so the README shows rendered pages rather than mock claims.

Demo Lab Product landing and demo index published on GitHub Pages.

2048 Web Touch-first generated HTML game for mobile WebView checks.

GitHub Test Browser-side token and repo access verification page.

Scene	What to try	Link
Demo Lab	A static landing page for published mobile demos	Open demo lab
2048 Web	Touch-first generated HTML game, useful for WebView and mobile layout checks	Play 2048
GitHub Test	Verify token identity, repo access, and Pages readiness from a browser	Open GitHub test
Repo Hub	Watch repos, map them to mobilecode_projects/github/<owner>/<repo>/, inspect Actions, edit files through GitHub API	mobile_agent/lib/screens/github_repo_hub_screen.dart
Published Work Card	After Pages publish, show Pages URL, repo URL, local file path, browser open, copy/share, and redeploy actions	mobile_agent/lib/screens/home_screen.dart

Product Loop

flowchart LR
  A["User prompt on phone"] --> B["AI generates HTML / code artifact"]
  B --> C["Local WebView preview"]
  C --> D["HTML publish readiness check"]
  D --> E["GitHub Pages publish"]
  E --> F["Shareable work card"]
  B --> G["GitHub Repo Hub"]
  G --> H["Contents API edit + commit"]
  G --> I["GitHub Actions workflow_dispatch"]
  I --> J["Jobs, logs, artifacts"]

Loading

Current Capabilities

• Runtime abstraction: RuntimeProvider, RuntimeManager, Helper, External Termux, planned Embedded Lite, Cloud, and WebViewOnly fallback.
• MobileCode Helper prototype: health, execute, streaming logs, task stop, task state, preflight checks.
• Chat and agent process UI: model call progress, stop control, trace cards, generated artifact cards.
• HTML-first generation: built-in HTML/UI skill context, publish readiness checks, WebView preview, browser open, GitHub Pages publish.
• GitHub-first workspace: repo list, watchlist, language/Pages/local filters, local existence status, Remote-linked folder marker.
• GitHub Actions surface: workflows, latest run status, jobs/steps, workflow dispatch, artifact zip download record.
• API-backed file flow: browse remote tree, read text files, edit, commit via GitHub Contents API, reload on SHA conflict.
• Extension management: Roles, Skill, MCP, Memory, Agent, Hook Registry surfaces for role-based workflows.
• Observability: RR AgentView, pending role approvals, Token Usage/cache-hit statistics, searchable/sortable LiteLLM-style pricing with manual snapshot checks, and Device Telemetry htop-style phone health.
• Lark CLI connector: opt-in diagnostics and structured dry-run action model.

Architecture

flowchart TB
  UI["Flutter App\nChat · Files · Preview · Settings"] --> RM["RuntimeManager"]
  RM --> H["MobileCode Helper\nAndroid foreground service / daemon"]
  RM --> T["External Termux\nfallback shell"]
  RM --> W["WebViewOnly\npreview-only fallback"]
  RM --> C["Cloud Runtime\nheavy tasks later"]
  UI --> GH["GitHub Deep Service"]
  GH --> Repo["Repos / Contents API"]
  GH --> Pages["GitHub Pages"]
  GH --> Actions["GitHub Actions"]
  Actions --> Artifacts["APK / Web / release artifacts"]

Loading

Quick Start

Try the published demos

Open:

• Demo Lab
• 2048 Web Demo
• GitHub Test

Build the product site

cd app
npm install
npm run build

Build the Flutter app

Local Flutter SDK is required:

cd mobile_agent
flutter pub get
flutter create --platforms=android,ios .
flutter build apk --release

For release QA, prefer GitHub Actions so the build is reproducible:

• Mobile Runtime CI
• Build Android APK
• Android App Smoke Test

Runtime Strategy

MobileCode does not try to become a full Termux clone. The long-term model is:

Flutter App
  -> RuntimeProvider abstraction
  -> MobileCode Helper
  -> External Termux fallback
  -> Embedded Lite runtime later
  -> Cloud runtime for heavy builds
  -> GitHub Pages + GitHub Actions for shipping

That keeps the phone lightweight while still letting users produce shareable web pages, inspect repos, commit small changes, and build APKs through GitHub Actions.

Repository Structure

.
├─ app/                     React/Vite product site
├─ docs/                    GitHub Pages demos, QA docs, runtime docs
├─ mobile_agent/            Flutter app source
│  ├─ lib/screens/          Home, GitHub Repo Hub, Skill/MCP/Agent/Memory UI
│  ├─ lib/services/         Runtime, GitHub, Pages, Helper, skill services
│  └─ assets/               Role avatars and icons
├─ mobile-coding-*.md       Product and architecture analysis
└─ README.md                Project homepage

Release Line

Current candidate: 0.1.24+43.

See:

• Version Policy
• Release QA Checklist
• Helper Runtime Protocol
• Production Hardening Notes

Roadmap

Priority	Next focus	Stop condition
P0	Pass Mobile Runtime CI, Android APK build, Android smoke test for the pushed commit	APK artifact is downloadable and app launches
P1	Smooth Repo Hub file edit conflict handling and artifact download UX	User can recover from SHA conflicts and find downloaded artifacts
P2	Expand API-backed workspace into selected repo file import/export	Phone can edit selected repo files without true clone
Later	Helper APK maturity, queue recovery, PTY, cloud heavy builds	Runtime remains replaceable behind RuntimeProvider

Status

This repository is actively moving toward a deployable mobile coding workspace. The Android build path is GitHub Actions-first; local machines without Flutter/Android SDK should use CI artifacts instead of local builds.

License

No license file is included yet. Add a LICENSE before treating this as a reusable open-source distribution.