# droidrun/mobilerun architecture

> Architecture diagram of the GitHub repository droidrun/mobilerun, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/droidrun/mobilerun
- Repository: https://github.com/droidrun/mobilerun

## Overview

Mobilerun is a framework for LLM-driven Android and iOS automation. A user starts a task through the CLI or Python API; an agent interprets it, observes device state, issues mobile actions, and returns a result. Reasoning mode adds manager-led planning, while direct tasks, vision, structured output, app cards, custom tools, macros, MCP, and tracing provide distinct capabilities. The README documents the product workflow; source excerpts and the index confirm selected implementation links, but many runtime integrations were not sampled.

Main entry points: [`mobilerun/cli/main.py`](https://github.com/droidrun/mobilerun/blob/main/mobilerun/cli/main.py) (CLI), [`mobilerun/agent/manager/manager_agent.py`](https://github.com/droidrun/mobilerun/blob/main/mobilerun/agent/manager/manager_agent.py) (Reasoning manager), [`mobilerun/agent/utils/llm_picker.py`](https://github.com/droidrun/mobilerun/blob/main/mobilerun/agent/utils/llm_picker.py) (Model selection), [`mobilerun/agent/fast_agent/fast_agent.py`](https://github.com/droidrun/mobilerun/blob/main/mobilerun/agent/fast_agent/fast_agent.py) (Direct agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and setup"]
  node_cli["CLI<br/>[main.py]"]
  node_config["Configuration<br/>[config_manager.py]"]
end

subgraph group_agents["Agent runtime"]
  node_manager["Reasoning manager<br/>[manager_agent.py]"]
  node_fast["Direct agent<br/>[fast_agent.py]"]
  node_executor["Action executor<br/>[executor_agent.py]"]
  node_tools["Tool registry<br/>[tool_registry.py]"]
  node_structured["Structured workflows"]
end

subgraph group_device["Mobile interaction"]
  node_state["UI state provider<br/>[provider.py]"]
  node_driver["Device drivers"]
  node_ios["iOS provider<br/>[ios_provider.py]"]
  node_android["Android Portal<br/>[droid_agent.py]"]
end

subgraph group_extensions["Workflow extensions"]
  node_cards["App cards"]
  node_macro["Macro replay<br/>[replay.py]"]
  node_mcp["MCP integration<br/>[client.py]"]
end

subgraph group_services["Models and observability"]
  node_llm["Model selection<br/>[llm_picker.py]"]
  node_providers["Provider registry<br/>[registry.py]"]
  node_oauth["OAuth providers"]
  node_authstore[("Auth profiles")]
  node_trajectory["Trajectory writer<br/>[writer.py]"]
  node_telemetry["Tracing telemetry<br/>[tracker.py]"]
end

node_user(("Task author"))
node_device(("Phone"))
node_modelservice(("LLM services"))

node_user -->|"submits task"| node_cli
node_cli -->|"loads settings"| node_config
node_cli -->|"runs reasoning"| node_manager
node_cli -->|"runs direct task"| node_fast
node_manager -.->|"plans actions"| node_executor
node_manager -->|"reads UI state"| node_state
node_manager -->|"loads guidance"| node_cards
node_fast -->|"observes device"| node_state
node_executor -.->|"dispatches actions"| node_tools
node_tools -.->|"uses device tools"| node_driver
node_state -->|"fetches device data"| node_driver
node_driver -->|"controls"| node_device
node_ios -->|"targets iOS"| node_device
node_android -->|"controls Android"| node_device
node_cli -->|"selects iOS"| node_ios
node_cli -.->|"runs structured flow"| node_structured
node_cli -->|"replays macros"| node_macro
node_config -->|"configures servers"| node_mcp
node_manager -->|"requests inference"| node_llm
node_fast -.->|"requests inference"| node_llm
node_llm -->|"resolves model"| node_providers
node_llm -->|"sends prompts"| node_modelservice
node_oauth -->|"stores credentials"| node_authstore
node_manager -.->|"records execution"| node_trajectory
node_cli -.->|"enables tracing"| node_telemetry

click node_cli "https://github.com/droidrun/mobilerun/blob/main/mobilerun/cli/main.py"
click node_config "https://github.com/droidrun/mobilerun/blob/main/mobilerun/config_manager/config_manager.py"
click node_manager "https://github.com/droidrun/mobilerun/blob/main/mobilerun/agent/manager/manager_agent.py"
click node_fast "https://github.com/droidrun/mobilerun/blob/main/mobilerun/agent/fast_agent/fast_agent.py"
click node_executor "https://github.com/droidrun/mobilerun/blob/main/mobilerun/agent/executor/executor_agent.py"
click node_tools "https://github.com/droidrun/mobilerun/blob/main/mobilerun/agent/tool_registry.py"
click node_structured "https://github.com/droidrun/mobilerun/blob/main/mobilerun/agent/oneflows/structured_output_agent.py"
click node_state "https://github.com/droidrun/mobilerun/blob/main/mobilerun/tools/ui/provider.py"
click node_driver "https://github.com/droidrun/mobilerun/tree/main/mobilerun/tools/driver"
click node_ios "https://github.com/droidrun/mobilerun/blob/main/mobilerun/tools/ui/ios_provider.py"
click node_android "https://github.com/droidrun/mobilerun/blob/main/mobilerun/agent/droid/droid_agent.py"
click node_cards "https://github.com/droidrun/mobilerun/blob/main/mobilerun/app_cards/app_card_provider.py"
click node_macro "https://github.com/droidrun/mobilerun/blob/main/mobilerun/macro/replay.py"
click node_mcp "https://github.com/droidrun/mobilerun/blob/main/mobilerun/mcp/client.py"
click node_llm "https://github.com/droidrun/mobilerun/blob/main/mobilerun/agent/utils/llm_picker.py"
click node_providers "https://github.com/droidrun/mobilerun/blob/main/mobilerun/agent/providers/registry.py"
click node_oauth "https://github.com/droidrun/mobilerun/blob/main/mobilerun/agent/utils/oauth/openai_oauth_llm.py"
click node_authstore "https://github.com/droidrun/mobilerun/blob/main/mobilerun/config_manager/auth_profile_store.py"
click node_trajectory "https://github.com/droidrun/mobilerun/blob/main/mobilerun/agent/trajectory/writer.py"
click node_telemetry "https://github.com/droidrun/mobilerun/blob/main/mobilerun/telemetry/tracker.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_config toneBlue
class node_manager,node_fast,node_executor,node_tools,node_structured toneAmber
class node_state,node_driver,node_ios,node_android toneMint
class node_cards,node_macro,node_mcp,node_user toneRose
class node_llm,node_providers,node_oauth,node_authstore,node_trajectory,node_telemetry,node_device,node_modelservice toneIndigo
```

## Components

### Entry and setup

- [CLI](https://github.com/droidrun/mobilerun/blob/main/mobilerun/cli/main.py): `mobilerun/cli/main.py`
- [Configuration](https://github.com/droidrun/mobilerun/blob/main/mobilerun/config_manager/config_manager.py): `mobilerun/config_manager/config_manager.py`

### Agent runtime

- [Reasoning manager](https://github.com/droidrun/mobilerun/blob/main/mobilerun/agent/manager/manager_agent.py): `mobilerun/agent/manager/manager_agent.py`
- [Direct agent](https://github.com/droidrun/mobilerun/blob/main/mobilerun/agent/fast_agent/fast_agent.py): `mobilerun/agent/fast_agent/fast_agent.py`
- [Action executor](https://github.com/droidrun/mobilerun/blob/main/mobilerun/agent/executor/executor_agent.py): `mobilerun/agent/executor/executor_agent.py`
- [Tool registry](https://github.com/droidrun/mobilerun/blob/main/mobilerun/agent/tool_registry.py): `mobilerun/agent/tool_registry.py`
- [Structured workflows](https://github.com/droidrun/mobilerun/blob/main/mobilerun/agent/oneflows/structured_output_agent.py): `mobilerun/agent/oneflows/structured_output_agent.py`

### Mobile interaction

- [UI state provider](https://github.com/droidrun/mobilerun/blob/main/mobilerun/tools/ui/provider.py): `mobilerun/tools/ui/provider.py`
- [Device drivers](https://github.com/droidrun/mobilerun/tree/main/mobilerun/tools/driver): `mobilerun/tools/driver`
- [iOS provider](https://github.com/droidrun/mobilerun/blob/main/mobilerun/tools/ui/ios_provider.py): `mobilerun/tools/ui/ios_provider.py`
- [Android Portal](https://github.com/droidrun/mobilerun/blob/main/mobilerun/agent/droid/droid_agent.py): `mobilerun/agent/droid/droid_agent.py`

### Workflow extensions

- [App cards](https://github.com/droidrun/mobilerun/blob/main/mobilerun/app_cards/app_card_provider.py): `mobilerun/app_cards/app_card_provider.py`
- [Macro replay](https://github.com/droidrun/mobilerun/blob/main/mobilerun/macro/replay.py): `mobilerun/macro/replay.py`
- [MCP integration](https://github.com/droidrun/mobilerun/blob/main/mobilerun/mcp/client.py): `mobilerun/mcp/client.py`

### Models and observability

- [Model selection](https://github.com/droidrun/mobilerun/blob/main/mobilerun/agent/utils/llm_picker.py): `mobilerun/agent/utils/llm_picker.py`
- [Provider registry](https://github.com/droidrun/mobilerun/blob/main/mobilerun/agent/providers/registry.py): `mobilerun/agent/providers/registry.py`
- [OAuth providers](https://github.com/droidrun/mobilerun/blob/main/mobilerun/agent/utils/oauth/openai_oauth_llm.py): `mobilerun/agent/utils/oauth/openai_oauth_llm.py`
- [Auth profiles](https://github.com/droidrun/mobilerun/blob/main/mobilerun/config_manager/auth_profile_store.py): `mobilerun/config_manager/auth_profile_store.py`
- [Trajectory writer](https://github.com/droidrun/mobilerun/blob/main/mobilerun/agent/trajectory/writer.py): `mobilerun/agent/trajectory/writer.py`
- [Tracing telemetry](https://github.com/droidrun/mobilerun/blob/main/mobilerun/telemetry/tracker.py): `mobilerun/telemetry/tracker.py`

### Other components

- **Task author**
- **Phone**
- **LLM services**

## Connections

- Task author → CLI: submits task
- CLI → Configuration: loads settings (evidence: `mobilerun/cli/main.py`)
- CLI → Reasoning manager: runs reasoning
- CLI → Direct agent: runs direct task
- Reasoning manager → Action executor: plans actions
- Reasoning manager → UI state provider: reads UI state (evidence: `mobilerun/agent/manager/manager_agent.py`)
- Reasoning manager → App cards: loads guidance (evidence: `mobilerun/agent/manager/manager_agent.py`)
- Direct agent → UI state provider: observes device
- Action executor → Tool registry: dispatches actions
- Tool registry → Device drivers: uses device tools
- UI state provider → Device drivers: fetches device data (evidence: `mobilerun/tools/ui/provider.py`)
- Device drivers → Phone: controls
- iOS provider → Phone: targets iOS
- Android Portal → Phone: controls Android
- CLI → iOS provider: selects iOS
- CLI → Structured workflows: runs structured flow
- CLI → Macro replay: replays macros (evidence: `mobilerun/cli/main.py`)
- Configuration → MCP integration: configures servers (evidence: `mobilerun/config_manager/config_manager.py`)
- Reasoning manager → Model selection: requests inference (evidence: `mobilerun/agent/manager/manager_agent.py`)
- Direct agent → Model selection: requests inference
- Model selection → Provider registry: resolves model (evidence: `mobilerun/agent/utils/llm_picker.py`)
- Model selection → LLM services: sends prompts
- OAuth providers → Auth profiles: stores credentials (evidence: `mobilerun/agent/utils/oauth/openai_oauth_llm.py`)
- Reasoning manager → Trajectory writer: records execution
- CLI → Tracing telemetry: enables tracing
