Mobium is one Go binary. Every way in — the CLI, an MCP client, the five language clients — reaches the same tool layer, and the tool layer reaches every device through one driver interface. Only the bottom layer knows which platform it is on.
flowchart TB
subgraph doors["Front doors"]
cli["CLI<br/>mobium map, mobium tap @e5"]
clients["Language clients<br/>Python · JavaScript · Go · Java · .NET"]
mcp["MCP client<br/>an agent"]
test["mobium test<br/>JSON test files · --ui page"]
inspect["mobium inspect<br/>a page showing the screen"]
end
pipe["mobium pipe<br/>JSON-RPC on stdio"]
mcpcmd["mobium mcp<br/>MCP on stdio, in-process"]
daemon["Daemon<br/>Unix socket · named pipe on Windows<br/>holds sessions and the @ref table"]
cli --> daemon
clients --> pipe --> daemon
mcp --> mcpcmd
test --> daemon
test -- "a pipe per project on a grid" --> pipe
inspect --> daemon
remote["another machine's daemon<br/>--remote, MOBIUM_GRID"]
cli & pipe -.->|"SSH socket forward"| remote
subgraph core["internal/agent — the tool layer, written once"]
tools["Tools and schemas<br/>map · tap · type · wait · scroll-to · alert · …"]
refs["@refs, locators, auto-wait,<br/>dialog and keyboard refusals"]
end
daemon --> tools
mcpcmd --> tools
tools --- refs
tree["internal/uitree<br/>platform-neutral node tree"]
web["internal/webview<br/>CDP · Remote Web Inspector"]
refs --> tree
tools --> web
subgraph drivers["internal/mobiumdriver — the only platform-specific layer"]
uia2["uiautomator2<br/>Android default"]
dump["uiautomator<br/>Android, installs nothing"]
wda["wda<br/>iOS simulator and iPhone"]
ext["external driver<br/>mobium-driver-NAME"]
end
tools --> uia2 & dump & wda & ext
subgraph devicepkg["internal/device — finding and readying devices"]
adb["adb"]
simctl["simctl"]
devicectl["devicectl · CoreDevice"]
lockdown["usbmuxd · lockdown"]
end
uia2 -- "HTTP over adb forward" --> uiaserver["UiAutomator2 server<br/>on the device"]
uia2 --> adb
dump -- "uiautomator dump" --> adb
wda -- "HTTP" --> wdarunner["WebDriverAgent runner<br/>on the simulator or phone"]
wda --> simctl & devicectl
ext -- "JSON-RPC on stdio" --> other["any platform:<br/>a TV, a desktop app, …"]
web -- "Android: devtools socket" --> adb
web -- "iPhone: com.apple.webinspector" --> lockdown
- The CLI does not implement behavior. It parses flags and calls a tool by name, so the CLI, MCP and every client get identical behavior.
- Clients go through the daemon, via
mobium pipe, never throughmobium mcp. A device-side server holds one session at a time, so a client with its own session would invalidate the CLI's. mobium mcpruns the tool layer in-process, because an MCP client already holds a long-lived connection of its own.- Reads in a WebView go over its debugging protocol; taps stay native. The page's coordinates are converted to device pixels and the tap is delivered by the ordinary driver.
- A third-party backend is a process, not a Go plugin: any executable named
mobium-driver-<name>onPATH, speaking JSON-RPC (the driver protocol).
Arrows point from a package to the packages it imports. This is the import
graph as it stands, not an aspiration: internal/apisurface checks the surface
on every build, and nothing imports cmd/.
flowchart LR
cmd["cmd/mobium<br/>CLI, pipe, mcp"]
daemon["internal/daemon<br/>socket, PID, idle exit"]
agent["internal/agent<br/>tools, schemas, @refs"]
apisurface["internal/apisurface<br/>drift checks"]
driver["internal/mobiumdriver<br/>backends"]
webview["internal/webview<br/>CDP, RWI"]
formflux["internal/formflux<br/>screen profiles"]
testrun["internal/testrun<br/>mobium test"]
testui["internal/testui<br/>mobium test --ui"]
inspect["internal/inspect<br/>mobium inspect"]
grid["internal/grid<br/>leases on a node"]
trace["internal/trace<br/>session recording"]
uitree["internal/uitree<br/>nodes, locators, map"]
device["internal/device<br/>adb, simctl, devicectl, lockdown"]
plist["internal/plist<br/>property lists"]
paths["internal/paths"]
err["internal/mobiumerr<br/>error codes"]
cmd --> agent & daemon & testrun & testui & inspect & grid & device & paths
daemon --> agent & paths
apisurface --> agent
testrun --> agent
testui --> testrun
inspect --> agent & testrun & uitree
agent --> driver & webview & formflux & uitree & device & grid & trace & paths
grid --> paths
driver --> device & uitree
webview --> device & uitree & plist
formflux --> uitree
device --> plist & paths
Nearly every package also imports internal/mobiumerr, left out above for
legibility; only internal/trace, internal/testui and the test helper
internal/fakecmd do not. Every failure carries one of its codes, which are
public API
(the codes).
| Package | Responsibility |
|---|---|
cmd/mobium |
the CLI: flags in, a tool call out. Also pipe and mcp |
internal/daemon |
the long-lived process that holds device sessions and refs |
internal/agent |
every tool: its schema, its handler, waiting, scrolling, refusals |
internal/uitree |
the platform-neutral hierarchy, locators, map and password redaction |
internal/mobiumdriver |
the Driver interface and its backends, each advertising what it can do |
internal/webview |
finding WebViews and speaking CDP or Remote Web Inspector to them |
internal/device |
adb, simctl, devicectl, usbmuxd and lockdown; installing the pinned device agents |
internal/formflux |
one device impersonating many screens (FORMFLUX.md) |
internal/plist |
the property-list codec iOS's inspector and lockdown speak |
internal/testrun |
mobium test: JSON test files run through the tools, with retries, workers and reports |
internal/testui |
mobium test --ui: a page that runs the suite and shows each step |
internal/inspect |
mobium inspect: a page showing the screen and its elements, recording a test file |
internal/grid |
a grid node's device leases |
internal/trace |
recording a session in Vibium's record format |
internal/apisurface |
build-time checks that every tool and flag is reachable from every front door |
internal/paths |
socket, PID and session paths, and the OS length limit on them |
internal/mobiumerr |
the error codes |
mobium tap @e5, on Android with the default backend:
sequenceDiagram
participant CLI as mobium tap @e5
participant D as daemon
participant A as internal/agent
participant U as uiautomator2 driver
participant S as UiAutomator2 server
CLI->>D: tools/call app_tap {target: "@e5"}
D->>A: dispatch
A->>A: look up @e5's locator from the last map
loop until settled, or the wait runs out
A->>U: snapshot
U->>S: GET /source
S-->>U: hierarchy
U-->>A: nodes
A->>A: resolve the locator to exactly one node,<br/>check it is in view, still, enabled,<br/>and not under a dialog or the keyboard
end
A->>U: tap at the node's center
U->>S: W3C actions
S-->>U: ok
A-->>D: result, with any dialog it answered
D-->>CLI: "tapped @e5 at (540, 930)"
The ref is re-resolved against a fresh snapshot before the tap. The
coordinates from the earlier map are never replayed, because the screen moves
between commands. A locator that now matches nothing, or more than one thing,
is refused with a code rather than tapped.
Pixels are what map bounds, screenshots and taps use on every platform.
WebDriverAgent reports points; the iOS driver converts them to pixels at the
driver boundary, so nothing above internal/mobiumdriver sees a point.
WebView coordinates are CSS pixels, converted using the WebView's on-screen
frame and the page's visual viewport.