Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 6 additions & 4 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
# CLAUDE.md

Mobile app automation for AI agents and humans: native apps on Android
emulators and phones, iOS simulators and iPhones, WebViews included — one Go
binary, driven from a CLI, an MCP server, or five language clients.
Mobile app automation for AI agents and humans: native, hybrid and
cross-platform apps, and pages in a mobile browser or installed as a PWA, on
Android emulators and phones, iOS simulators and iPhones — one Go binary,
driven from a CLI, an MCP server, or five language clients. docs/APP-TYPES.md
says which app types were driven and how; a claim about one goes there too.

## Key Docs

Expand All @@ -11,7 +13,7 @@ binary, driven from a CLI, an MCP server, or five language clients.
- docs/ARCHITECTURE.md — every layer, and one call traced end to end
- docs/API.md and docs/FLAGS.md — every tool and argument, generated
- docs/CHALLENGES.md — every defect and what it taught. Read before asserting platform behavior
- docs/decisions/ — the design records; docs/guides/ — how to use each surface
- docs/guides/ — how to use each surface; examples/drivers/PROTOCOL.md — the driver protocol
- docs/ROADMAP.md — what is next

## Tech Stack
Expand Down
4 changes: 2 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Anderson's "The Three-Cornered Wheel" — and the rule applied across the codeba

- `internal/mobiumdriver` is the only platform-specific layer. Everything above
it is written once. A third party adds a backend as a **driver process**
([decisions/0003](docs/decisions/0003-drivers-are-processes-not-plugins.md)),
([the driver protocol](examples/drivers/PROTOCOL.md)),
not by importing this package.
- `internal/device` finds, launches and readies the thing being automated.
- The CLI parses flags and calls a tool by name. Behavior lives in
Expand Down Expand Up @@ -60,7 +60,7 @@ old binary.
- **Every error has a code.** Create one with `mobiumerr.New(mobiumerr.<Code>,
...)`, never a bare `fmt.Errorf` or `errors.New`. The codes are public API,
the same in every client and in the CLI's exit status
([decisions/0005](docs/decisions/0005-errors.md)).
([the codes](docs/guides/cli.md#6-when-a-command-fails)).
- A tool that fails returns `isError` with an explanation, never a JSON-RPC
error. An error that suggests a remedy must suggest one that can work.

Expand Down
43 changes: 31 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,15 @@

*Mutatis mutandis.*

**Native app automation for AI agents and humans.** Android emulators, Android
**Mobile app automation for AI agents and humans.** Android emulators, Android
phones, iOS simulators and iPhones, driven through one tool layer from a single
Go binary with no runtime dependencies.

```sh
mobium launch com.example.shop && mobium map && mobium tap @e5 && mobium map
```

Mobium drives native mobile apps the way [Vibium](https://github.com/VibiumDev/vibium)
Mobium drives mobile apps the way [Vibium](https://github.com/VibiumDev/vibium)
drives browsers: a `map` → `@ref` → act loop that an agent can follow without
learning a new model. It is Vibium's architecture with the browser swapped for
a device.
Expand All @@ -25,6 +25,7 @@ person driving an emulator for it. People get the same commands.
- [Quick start](#quick-start)
- [How it works](#how-it-works)
- [Platforms](#platforms)
- [App types](#app-types)
- [Hybrid apps and WebViews](#hybrid-apps-and-webviews)
- [Front doors](#front-doors)
- [Drivers for other platforms](#drivers-for-other-platforms)
Expand Down Expand Up @@ -188,13 +189,32 @@ simulated location — are refused on a phone with the reason; accessibility
settings go through the phone's own Settings app.
[docs/SETUP.md](docs/SETUP.md#ios-real-device) has the steps.

**Windows is not supported yet.** Everything cross-compiles for Windows, and
the daemon transport is written but not yet verified on a Windows machine; see
**Windows is not supported yet.** Everything that needs no device, the
named-pipe daemon transport included, passes in CI on a Windows runner; no
emulator or phone has been driven from Windows yet. See
[docs/WINDOWS.md](docs/WINDOWS.md).

Both device-side agents are pinned by version, verified against checksums
compiled into the binary, and refused on a mismatch.

## App types

What an app is built with decides where its elements are, so it decides what
Mobium reaches. Each type has been driven on a device:

| Type | How Mobium reaches it | Driven here |
| --- | --- | --- |
| **Native** — Android SDK, Jetpack Compose, UIKit, SwiftUI | the platform's accessibility tree | Settings, Calculator, Clock, Wikipedia, F-Droid, Aegis, Seal (Compose), NetNewsWire |
| **Hybrid** — a native shell around WebViews | the shell through the tree; each WebView as its own context, [below](#hybrid-apps-and-webviews) | Wikipedia's articles, MobiumApp's web screens |
| **Mobile web and PWAs** — a page in a browser, or installed to the home screen | the browser's page as a context; on iOS, taps through the native tree | Safari, Chrome, Squoosh as a PWA — on Android a PWA's taps only while Chrome reports its WebView |
| **Cross-platform, native once removed** — React Native | an ordinary native app: it renders real native views | MobiumApp, on both platforms and on real phones |
| **Cross-platform that paints** — Flutter | not through the tree; a job for a [driver](#drivers-for-other-platforms) | not yet |

A browser is reachable but not managed — no tabs, no browser sessions; testing
a website is [Vibium](https://github.com/VibiumDev/vibium)'s job.
[docs/APP-TYPES.md](docs/APP-TYPES.md) has what was measured for each type,
what is checked in and what was driven only once.

## Hybrid apps and WebViews

A hybrid app's web content is not usable through the accessibility tree, so
Expand All @@ -218,9 +238,8 @@ tapped @e2 at (462, 397) in WEBVIEW_com.example
mapped by a script, its CSS coordinates are converted to device pixels using
the WebView's on-screen frame and the page's visual viewport, and the tap is
delivered by the native driver like any other. Android WebViews speak CDP; iOS
WKWebViews speak WebKit's Remote Web Inspector
([decisions/0001](docs/decisions/0001-cdp-not-webdriver-bidi.md),
[0002](docs/decisions/0002-ios-webviews-are-reachable.md)).
WKWebViews speak WebKit's Remote Web Inspector, over a Unix socket on a
simulator and through usbmuxd and lockdown on a phone.

A WebView is reachable only if the app opted in —
`WebView.setWebContentsDebuggingEnabled(true)` on Android, `isInspectable` on
Expand Down Expand Up @@ -323,8 +342,8 @@ A driver needs three methods to be useful — `snapshot`, `screenshot` and
`tap` — and inherits locators, `@ref`s, waiting, scrolling, the CLI, MCP and
all five clients. [examples/drivers/](examples/drivers/) has the guide and a
complete driver in dependency-free Python that produces the same map as the
built-in backend; [decisions/0003](docs/decisions/0003-drivers-are-processes-not-plugins.md)
is the protocol.
built-in backend; [PROTOCOL.md](examples/drivers/PROTOCOL.md) is the
protocol.

## Documentation

Expand All @@ -348,16 +367,16 @@ is the protocol.
| [docs/WINDOWS.md](docs/WINDOWS.md) | the state of Windows support |
| [docs/ROADMAP.md](docs/ROADMAP.md) | what is next |
| [docs/RELEASE-CHECKLIST.md](docs/RELEASE-CHECKLIST.md) | the device checks CI cannot run |
| [docs/decisions/](docs/decisions/) | architecture decision records |
| [examples/drivers/PROTOCOL.md](examples/drivers/PROTOCOL.md) | the protocol a third-party driver speaks |
| [docs/checks/](docs/checks/) | end-to-end scripts that drive a real device |
| [examples/drivers/](examples/drivers/) | writing a driver |
| [CONTRIBUTING.md](CONTRIBUTING.md) | building, testing and the project's rules |

Several checks drive **[MobiumApp](https://github.com/mobiumdev/mobium-app)**,
a React Native app built to be driven: each screen is a control for a case
that can go wrong, and on iOS it is the only way to reach an app's WebView,
since one that has not opted into inspection is invisible to any debugger
([decisions/0004](docs/decisions/0004-an-app-under-test-of-our-own.md)).
since one that has not opted into inspection (`isInspectable`) is invisible
to any debugger, and that cannot be forced from outside.

## License

Expand Down
2 changes: 1 addition & 1 deletion assets/branding/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -134,7 +134,7 @@ Wheel", is in [docs/PHILOSOPHY.md](../../docs/PHILOSOPHY.md).
Set it in italics, capitalized as a sentence — *Mutatis mutandis* — and do not
translate it inline in display use; the gloss belongs in body text, as above.
It pairs with the mark rather than replacing the descriptive line: the mark
says what it is called, "native app automation for AI agents and humans" says
says what it is called, "mobile app automation for AI agents and humans" says
what it does, and the motto says how it is built.

## Namespace
Expand Down
2 changes: 1 addition & 1 deletion clients/dotnet/Mobium/Device.cs
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
namespace Mobium
{
/// <summary>
/// Drives native apps on Android emulators, Android phones, iOS
/// Drives mobile apps on Android emulators, Android phones, iOS
/// simulators and iPhones.
/// </summary>
/// <remarks>
Expand Down
2 changes: 1 addition & 1 deletion clients/dotnet/Mobium/Mobium.csproj
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@
<PackageId>Mobium</PackageId>
<Version>0.1.0</Version>
<Authors>Lana Begunova</Authors>
<Description>Drives native apps on Android emulators, Android phones, iOS simulators and iPhones, over the mobium CLI. No dependencies.</Description>
<Description>Drives mobile apps on Android emulators, Android phones, iOS simulators and iPhones, over the mobium CLI. No dependencies.</Description>
<Copyright>Copyright (c) 2026 Lana Begunova</Copyright>
<PackageLicenseExpression>MIT</PackageLicenseExpression>
<PackageProjectUrl>https://github.com/mobiumdev/mobium</PackageProjectUrl>
Expand Down
3 changes: 2 additions & 1 deletion clients/dotnet/Mobium/MobiumException.cs
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,8 @@ namespace Mobium
/// </summary>
/// <remarks>
/// Every tool failure carries a stable <see cref="Code"/>, the same in every
/// client and on the wire (docs/decisions/0005 in the mobium repository),
/// client and on the wire (the error codes in the mobium repository's
/// docs/guides/cli.md),
/// and each code has a subclass — <see cref="NoSuchElementException"/>,
/// <see cref="UnsupportedException"/> and so on — so a test catches the kind
/// it can handle and lets the rest through. <see cref="Remedy"/> says what
Expand Down
4 changes: 2 additions & 2 deletions clients/dotnet/README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Mobium for .NET

Drives native apps on Android emulators, Android phones, iOS simulators and
Drives mobile apps on Android emulators, Android phones, iOS simulators and
iPhones from C#.

```csharp
Expand Down Expand Up @@ -81,7 +81,7 @@ code, `Remedy` what to do about it, `Retryable` whether a retry can help, and
Each code has its own subclass — `NoSuchElementException`,
`AmbiguousLocatorException`, `UnsupportedException`, `NotConfirmedException`,
`TimedOutException` (not `TimeoutException`, which is .NET's) and the rest,
the same set in every client (`docs/decisions/0005-errors.md`) — so a test
the same set in every client ([the codes](../../docs/guides/cli.md#6-when-a-command-fails)) — so a test
catches the kind it can handle:

```csharp
Expand Down
2 changes: 1 addition & 1 deletion clients/dotnet/Tests/Program.cs
Original file line number Diff line number Diff line change
Expand Up @@ -738,7 +738,7 @@ private static void TraceSendsOnlyWhatWasGiven()

// -- the harness ----------------------------------------------------

// -- error codes: docs/decisions/0005 -----------------------------
// -- error codes: docs/guides/cli.md -------------------------------

private static readonly string[] Codes = {"no_device", "device_not_ready", "toolchain_missing",
"no_such_element", "ambiguous_locator", "element_not_reachable", "no_such_context",
Expand Down
2 changes: 1 addition & 1 deletion clients/go/README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Mobium for Go

Drive native apps on Android emulators, Android phones, iOS simulators and
Drive mobile apps on Android emulators, Android phones, iOS simulators and
iPhones — map the screen, tap, type, wait and screenshot — through the same
tools as the [mobium](https://github.com/mobiumdev/mobium) command line and
MCP server. Standard library only.
Expand Down
7 changes: 3 additions & 4 deletions clients/go/errors.go
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,8 @@ import (
)

// Code classifies a failure. The strings are Mobium's stable error codes,
// the same in every client and on the wire; see docs/decisions/0005 in the
// mobium repository. A client is not required to know every code: one it
// the same in every client and on the wire; see the error codes in the
// mobium repository's docs/guides/cli.md. A client is not required to know every code: one it
// does not recognize is still an *Error, with Code set.
type Code string

Expand Down Expand Up @@ -43,8 +43,7 @@ var (
ErrUnsupported = &Error{Code: CodeUnsupported}
ErrNotConfirmed = &Error{Code: CodeNotConfirmed}
// TimedOut, not Timeout, as in every client: Python's TimeoutError and
// Java's TimeoutException are builtins a Timeout name would shadow
// (docs/decisions/0005).
// Java's TimeoutException are builtins a Timeout name would shadow.
ErrTimedOut = &Error{Code: CodeTimeout}
ErrInvalidArgument = &Error{Code: CodeInvalidArgument}
ErrDeviceServer = &Error{Code: CodeDeviceServer}
Expand Down
2 changes: 1 addition & 1 deletion clients/go/mobium.go
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
// Package mobium drives native apps on Android emulators, Android phones, iOS
// Package mobium drives mobile apps on Android emulators, Android phones, iOS
// simulators and iPhones.
//
// It speaks to the same tool layer the CLI and the MCP server use, over
Expand Down
6 changes: 3 additions & 3 deletions clients/java/README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Mobium Java client

Drives native apps on Android emulators, Android phones, iOS simulators and
Drives mobile apps on Android emulators, Android phones, iOS simulators and
iPhones, over the same tool layer the CLI and the MCP server use.

```java
Expand Down Expand Up @@ -174,8 +174,8 @@ try {
`TimedOutException` (not `TimeoutException`, which is Java's),
`InvalidArgumentException`, `DeviceServerException`, `InternalException`.
Import `dev.mobium.NoSuchElementException` by name: it shares its simple name
with `java.util`'s, as Selenium's does. The codes are the same in every client;
see `docs/decisions/0005-errors.md`.
with `java.util`'s. The codes are the same in every client;
see [the codes](../../docs/guides/cli.md#6-when-a-command-fails).

### Threads, timeouts and closing

Expand Down
2 changes: 1 addition & 1 deletion clients/java/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@
<packaging>jar</packaging>

<name>Mobium Java client</name>
<description>Drives native apps on Android emulators, Android phones, iOS simulators and iPhones, over the mobium CLI. No dependencies.</description>
<description>Drives mobile apps on Android emulators, Android phones, iOS simulators and iPhones, over the mobium CLI. No dependencies.</description>
<url>https://github.com/mobiumdev/mobium</url>
<inceptionYear>2026</inceptionYear>

Expand Down
2 changes: 1 addition & 1 deletion clients/java/src/main/java/dev/mobium/Mobium.java
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
import java.util.Map;

/**
* Drives native apps on Android emulators, Android phones, iOS simulators
* Drives mobile apps on Android emulators, Android phones, iOS simulators
* and iPhones.
*
* <p>Speaks to the same tool layer the CLI and the MCP server use, over
Expand Down
4 changes: 2 additions & 2 deletions clients/java/src/main/java/dev/mobium/MobiumException.java
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,8 @@
* Mobium failed.
*
* <p>Every tool failure carries a stable {@link #code() code}, the same in
* every client and on the wire (docs/decisions/0005 in the mobium
* repository), and each code has a subclass — {@link NoSuchElementException},
* every client and on the wire (the error codes in the mobium
* repository's docs/guides/cli.md), and each code has a subclass — {@link NoSuchElementException},
* {@link UnsupportedException} and so on — so a test catches the kind it can
* handle and lets the rest through. {@link #remedy()} says what to do about
* it, {@link #retryable()} whether the same call can succeed if made again.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,8 @@
/**
* A locator or ref matched nothing on screen. Worth scrolling for.
*
* <p>Shares its simple name with {@code java.util.NoSuchElementException}, as
* Selenium's does; import this one by name rather than through a wildcard.
* <p>Shares its simple name with {@code java.util.NoSuchElementException};
* import this one by name rather than through a wildcard.
*
* <p>Error code {@code no_such_element}. See {@link MobiumException}.
*/
Expand Down
2 changes: 1 addition & 1 deletion clients/java/src/test/java/dev/mobium/Tests.java
Original file line number Diff line number Diff line change
Expand Up @@ -203,7 +203,7 @@ static void pathSearchSkipsRelativeDirectories() {
}
}

// -- error codes: docs/decisions/0005 -----------------------------------
// -- error codes: docs/guides/cli.md -------------------------------------

static final String[] CODES = {"no_device", "device_not_ready", "toolchain_missing",
"no_such_element", "ambiguous_locator", "element_not_reachable", "no_such_context",
Expand Down
2 changes: 1 addition & 1 deletion clients/javascript/README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Mobium for JavaScript

Drive native apps on Android emulators, Android phones, iOS simulators and
Drive mobile apps on Android emulators, Android phones, iOS simulators and
iPhones — map the screen, tap, type, wait and screenshot — through the same
tools as the [mobium](https://github.com/mobiumdev/mobium) command line and
MCP server. No dependencies; TypeScript declarations included.
Expand Down
6 changes: 3 additions & 3 deletions clients/javascript/index.js
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/**
* Mobium — native mobile app automation on emulators, simulators and phones.
* Mobium — mobile app automation on emulators, simulators and phones.
*
* import { start } from 'mobium'
*
Expand All @@ -16,8 +16,8 @@ import { createInterface } from 'node:readline'

/**
* A tool reported that it could not do what was asked. Every failure carries
* a stable code, the same in every client and on the wire (docs/decisions/0005
* in the mobium repository), and each code has a subclass below, so a script
* a stable code, the same in every client and on the wire (the error codes
* in the mobium repository's docs/guides/cli.md), and each code has a subclass below, so a script
* catches the kind it can handle:
*
* try { await device.tap('text=Continue') }
Expand Down
2 changes: 1 addition & 1 deletion clients/javascript/package.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "mobium",
"version": "0.1.0",
"description": "Drive native apps on Android emulators, Android phones, iOS simulators and iPhones. No dependencies.",
"description": "Drive mobile apps on Android emulators, Android phones, iOS simulators and iPhones. No dependencies.",
"keywords": ["mobile", "automation", "testing", "android", "ios", "uiautomator2", "webdriveragent", "mcp"],
"homepage": "https://github.com/mobiumdev/mobium/blob/main/docs/quickstart/javascript.md",
"bugs": "https://github.com/mobiumdev/mobium/issues",
Expand Down
2 changes: 1 addition & 1 deletion clients/python/README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Mobium for Python

Drive native apps on Android emulators, Android phones, iOS simulators and
Drive mobile apps on Android emulators, Android phones, iOS simulators and
iPhones — map the screen, tap, type, wait and screenshot — through the same
tools as the [mobium](https://github.com/mobiumdev/mobium) command line and
MCP server. No dependencies.
Expand Down
2 changes: 1 addition & 1 deletion clients/python/mobium/__init__.py
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
"""Mobium — native mobile app automation on emulators, simulators and phones.
"""Mobium — mobile app automation on emulators, simulators and phones.

from mobium import start

Expand Down
3 changes: 2 additions & 1 deletion clients/python/mobium/_errors.py
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
"""Mobium's failures, one exception per error code.

Every failure a tool reports carries a stable code — the same in every client
and on the wire (docs/decisions/0005 in the mobium repository). Each code has
and on the wire (the error codes in the mobium repository's
docs/guides/cli.md). Each code has
an exception here, all subclasses of MobiumError, so a script catches the kind
it can handle and lets the rest through::

Expand Down
2 changes: 1 addition & 1 deletion clients/python/pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
[project]
name = "mobium"
version = "0.1.0"
description = "Drive native apps on Android emulators, Android phones, iOS simulators and iPhones. No dependencies."
description = "Drive mobile apps on Android emulators, Android phones, iOS simulators and iPhones. No dependencies."
readme = "README.md"
requires-python = ">=3.9"
license = "MIT"
Expand Down
2 changes: 1 addition & 1 deletion cmd/mobium/grid.go
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ import (
"github.com/spf13/cobra"
)

// A grid is Selenium Grid's shape without its hub: MOBIUM_GRID names the
// A grid has no hub: MOBIUM_GRID names the
// nodes, the caller's own mobium routes each run to a free device that
// matches, and the lease that keeps a device to one run lives on the node, so
// callers on different machines cannot take the same one. Nothing new listens
Expand Down
Loading
Loading