PhoneCode

A private, native coding agent that runs entirely on your Android phone.

Support PhoneCode on Ko-fi · Website · Latest release

_{Support is optional and unlocks no features or services.}

PhoneCode runs the agent loop on your device. It reads, writes, and edits files in per-project
workspaces, runs Git and a bundled Alpine Linux environment locally, searches the web, and talks to
the model provider you choose. There is no general-purpose PhoneCode backend, telemetry, remote
execution service, or required account. The only developer-operated endpoint accepts AI-output
reports you explicitly submit. API keys live in the Android Keystore.

Interface

_{Conversation · Explicit action approval · Private model setup}

PhoneCode is an independent project inspired by OpenCode and interoperable with it. It is not a
build of OpenCode.

Not affiliated with OpenCode. PhoneCode is not built by, endorsed by, or affiliated with the
OpenCode team (Anomaly). The name "OpenCode" appears here only to describe interoperability and
origins. Parts of the agent (prompt structure, tool schemas, and loop design) are adapted from
OpenCode, which is MIT licensed (Copyright (c) 2025 opencode); see LICENSES.

Features

• On-device agent with bounded file and process tools, Git, durable todo lists, plan and build
  modes, user questions, subagents, cancellable web access, MCP servers, and progressive-disclosure
  skills. Tool input and bounded output remain inspectable from the chat timeline.
• On-device development runtime in active migration. The current arm64 Alpine/PRoot runtime is
  a sideload development prototype. The Google Play architecture is a software-emulated QEMU Linux
  VM so packages execute on a virtual CPU behind an isolated Android process. The app will not claim
  arbitrary outside-Play native package installation until that VM boundary passes its release gate.
• Providers: OpenCode Zen and Go, Anthropic, OpenAI, OpenRouter, Google, xAI, DeepSeek,
  Mistral, and custom endpoints. Models and reasoning levels refresh automatically from models.dev;
  ChatGPT sign-in uses the account's authenticated Codex catalog. You can enable or disable
  providers, hide models, and mark favourites. The agent can add providers and models itself by
  editing providers.json, which is hot-reloaded.
• Sign-in flows: GitHub uses the OAuth device flow (you type a code, with no tokens to paste)
  for push and pull. "Sign in with ChatGPT" (Codex, OAuth + PKCE) lets you use a paid ChatGPT plan
  as a provider through OpenAI's Responses API - no API key needed.
• Projects and sessions: chats are organized into folder-backed projects. Active-session state,
  partial turns, tool checkpoints, and todos survive restarts; project instructions can come from
  bounded root-level AGENTS.md or CLAUDE.md files.
• Skills and MCP management: seven starter skills ship with the app. Global and project skills can
  be created, edited, enabled, and hot-reloaded without restarting a chat. MCP configuration is
  validated before activation, reconnects live, and clears unavailable tools instead of leaving a
  stale tool surface.
• Phone files: link only the Android folders you choose, then keep reads and writes approval-gated
  or allow them automatically per your workspace settings.
• Streaming chat with reasoning traces, a tool-activity timeline, monochrome syntax
  highlighting, a context-window gauge, and per-model token limits that drive compaction.
• Crash-safe sessions with foreground execution, bounded pre-output retries, durable tool
  checkpoints, atomic local storage, cancellable network calls, and explicit recovery when Android
  interrupts or you stop a turn.
• Privacy by construction: keys are encrypted on-device, Android cloud backup is disabled, and
  manual chat/settings exports use a file you choose through the Storage Access Framework.

Building

Requirements: JDK 21 and the Android SDK (platform 37.0, build-tools 36). Android Studio is not
needed. PhoneCode supports Android 8.0 and newer.

./gradlew :app:assembleDebug
./gradlew :provider:test :tools:test :agent:test :app:testDebugUnitTest :app:lintDebug \
  :app:verifyLegalInventory :app:verifyPrototypeRuntimeBoundary

The project has four modules. :app holds the Compose UI and Android glue. :agent holds the loop,
prompts, and compaction. :provider holds the wire formats and catalog. :tools holds the file,
git, web, todo, MCP, and skills tooling. The three library modules are pure JVM and fully
unit-tested.

Google Play release artifacts remain intentionally blocked until the QEMU runtime, licensing, API,
and Android App Bundle audits pass. When that gate opens, use a dedicated upload key with Play App
Signing and keep it outside the repository.

Notes

• The GitHub sign-in ships with the gh CLI's public client id for personal builds. Register your own
  OAuth app (one checkbox: Enable Device Flow) before distributing.
• Codex (Sign in with ChatGPT) authenticates over OAuth + PKCE with a loopback redirect, stores the
  tokens encrypted, and talks to ChatGPT's Responses API backend. It needs a paid ChatGPT plan.
• The Terms of Service and Privacy Policy live in legal/ and are also shown in-app under
  Settings > About.
• The public Play policy URLs are https://dttdrv.xyz/phonecode-privacy and
  https://dttdrv.xyz/phonecode-terms after the website repository is deployed.
• The local execution architecture is documented in MOBILE_BACKEND.md.

Licenses

PhoneCode's original code is Copyright 2026 dttdrv and licensed under the
Apache License 2.0.

PhoneCode bundles and adapts open-source work. The full list is in THIRD_PARTY.md
and in-app under Settings > About > Open-source licenses. In particular:

• OpenCode (MIT, Copyright (c) 2025 opencode) - the agent's prompt structure, tool schemas, and
  loop design are adapted from OpenCode. PhoneCode is an independent project and is not affiliated
  with the OpenCode team.
• Mermaid (MIT) - inline diagram rendering. PRoot (GPL-2.0) and talloc (LGPL-3.0) -
  the Linux compatibility layer. BusyBox (GPL-2.0) and Alpine Linux - the bundled local
  development environment.

Vendored artifacts are pinned in VENDORED_CHECKSUMS and verified by the
repository checks.