# Let your agent see the app.

Canonical URL: https://autonom.yatsuk.me/

Mobile testing for AI coding agents

Your agent tests and debugs your app on an iOS Simulator or an Android emulator, and brings back the evidence.

- [Get started](https://autonom.yatsuk.me/docs/install/index.md)
- [Read the docs](https://autonom.yatsuk.me/docs/index.md)

*Terminal*

```
$ autonom ui wait --settled --timeout-ms 5000
{"ok": true, "settled": true, …}

$ autonom ui tree
{"ok": true, …, "nodes": […, {"ref": "n5", "role": "button", "text": null, "desc": "Continue", …}, …], …}

$ autonom ui tap --desc "Continue"
{"ok": true, "x": 196, "y": 605, "ref": "n5", …}
```

How it works

## Look. Act. Prove.

The same verbs work on an iOS Simulator and an Android emulator. A node has the same shape on both, so one skill drives either platform.

[Screen docs](https://autonom.yatsuk.me/docs/screen/index.md)

### 1. Look.

Read the screen as a compact accessibility tree, with a screenshot for proof.

```sh
autonom ui tree
```

### 2. Act.

Find and tap by what an element says, not by where it sits.

```sh
autonom ui tap --desc "Continue"
```

### 3. Prove.

Every step lands in the session journal with its result and your notes.

```sh
autonom journal
```

Before and after

## Exit 0 is not proof.

A tap that returns ok does not prove the screen changed. Your agent compares the tree or the screenshot before and after.

*Diagram: Before: the sign-in screen with Continue selected.*

Before

ui tap ok

*Diagram: After: the next screen, a list.*

After

To keep a pair comparable, pin the status bar on both platforms, the keyboard and locale on iOS, and turn animations off on Android. The status bar and keyboard pins fix state the app does not own.

The evidence ladder

## Climb as far as the claim needs.

Each rung is stronger evidence than the one below it. Your agent stops at the rung a claim needs and says which rung it reached.

[Evidence docs](https://autonom.yatsuk.me/docs/evidence/index.md)

1. Code
2. Unit and widget tests
3. Integration on an explicit target
4. Screenshot, UI tree and logs
5. Profile, memory and network
6. Before and after replay

One target

## Never a silent guess.

With more than one device ready, your agent names the one it means. Ambiguity is an error listing the candidates.

[Sessions docs](https://autonom.yatsuk.me/docs/sessions/index.md)

*An expected failure*

```
{"ok": false,
 "error_code": "ambiguous_target",
 "error": "2 ready targets; pass --target (or --platform)",
 "hint": "Candidates: android:emulator-5554, ios:…",
 "candidates": […]}
```

On stderr with exit code 2, so your agent branches on the code.

What it can do

## One toolkit for the whole check.

Skills your agent loads and one command line that answers in JSON. No MCP server needed.

### The screen, as structure.

UI and accessibility trees, screenshots and recordings, logs and crash reports. [Mobile Canvas](https://autonom.yatsuk.me/docs/canvas/index.md) streams the device to your browser at up to 60 frames a second, on Android and the iOS Simulator, and you can drive it there.

[Screen and evidence docs](https://autonom.yatsuk.me/docs/evidence/index.md)

Commands

- ui tree
- ui find
- screenshot
- record
- logs
- crash

### Input by meaning.

Find and tap by label, then swipe, type into the focused field and press keys. `ui wait --settled` holds until two consecutive trees match.

[Screen docs](https://autonom.yatsuk.me/docs/screen/index.md)

### Traffic, captured and mocked.

Watch HTTP and HTTPS traffic through a local proxy and swap in the response you need, fullest on Android. Capture starts only on an explicit flag, and exports to HAR. A screenshot taken during a mock is flagged as mocked.

[Network docs](https://autonom.yatsuk.me/docs/network/index.md)

### Flows you can replay.

Save a check as a strict YAML flow and replay it. A mistake is caught at its exact line, and a failed step can suggest close matches from its captured screen. Imports and exports flows within the Maestro Core Profile.

[Flows docs](https://autonom.yatsuk.me/docs/flows/index.md)

Reports

- HTML
- JUnit
- Allure
- agent JSON
- CSV

### A ticket, pre-tested.

Hand your agent a ticket and the change behind it. With `autonom pretest`, your agent plans every check before the first tap, drives them under an action budget and packs the evidence with a plain verdict for QA.

[Ticket pre-test docs](https://autonom.yatsuk.me/docs/pretest/index.md)

Verdicts

- pass
- fail
- blocked
- not_covered
- inconclusive

### Memory for each app.

Your agent keeps notes on each app in `~/.autonom/apps/`. A flow approved after consecutive clean replays, three by default, can become an App Skill in your project.

[App memory docs](https://autonom.yatsuk.me/docs/memory/index.md)

### Performance, measured.

Measure memory, CPU, frames and traces, fullest on Android. Performance skills cover Flutter, native Kotlin and Compose.

[Performance docs](https://autonom.yatsuk.me/docs/performance/index.md)

Safety

## Capture is always opt-in.

Starting the proxy, attaching a device and installing a CA each take their own flag, every time. Credentials in captured traffic are masked before it is written.

[Safety docs](https://autonom.yatsuk.me/docs/safety/index.md)

### Consent is never cached.

Capture needs `--i-understand-mitm` on every run, plus a typed phrase on an interactive terminal. No config file, environment variable or earlier grant stands in.

### Flow secrets are never saved.

Flow secrets never enter artifacts, and the journal keeps only scrubbed arguments.

### The proxy stays local.

It binds `127.0.0.1` with no flag to widen it, and host network settings are never changed.

Sessions live in `~/.autonom/sessions/`, outside any repository, so a capture cannot be committed by accident.

How it differs

## Where Autonom fits.

Several tools let a coding agent work with a mobile app. Maestro and Appium are test frameworks that also ship MCP servers, and mobile-mcp is an MCP server built for agents. Autonom is a command line with skills, made for checking and debugging an app on an emulator or Simulator and keeping the evidence.

Autonom, Maestro, Appium and mobile-mcp side by side

| Topic | Autonom | Maestro | Appium | mobile-mcp |
| --- | --- | --- | --- | --- |
| How an agent uses it | Skills plus a command line that answers in JSON; no MCP server | YAML flows through its command line; an MCP server built into that command line | WebDriver client code against an Appium server; the official Appium MCP server | An MCP server |
| Devices | Android emulator and iOS Simulator; Android phones in part ([see the FAQ](https://autonom.yatsuk.me/index.md#faq-devices)); no physical iPhone | Android emulator and phone, iOS Simulator, web browser; physical iPhones not yet supported | Android emulator and phone, iOS Simulator and iPhone, desktop platforms through drivers | Android emulator and phone, iOS Simulator and iPhone |
| Repeatable tests | Flow v1 files in strict YAML; imports, exports and runs Maestro flows within its Maestro Core Profile | YAML flows, with optional JavaScript | Test code in Java, Python, Ruby, C# and other languages | No test file format; the agent calls tools |
| App network traffic | A built-in local proxy for capture, mocking and HAR export, with consent every time | No built-in mocking in the current docs | A third-party plugin, Interceptor | Not in its tool list |
| Live device view | Mobile Canvas, a local browser page | Maestro Viewer, in a browser or an agent panel | Not covered here | A terminal mirror plugin for Ghostty or kitty |
| License | MIT | Apache-2.0; Maestro Studio is free but not open source, Maestro Cloud is paid | Apache-2.0, Appium MCP too | Apache-2.0; optional cloud devices |

Checked October 2026 against each project's own pages: [Maestro](https://maestro.dev/), [Appium](https://appium.io/), [Appium MCP](https://github.com/appium/appium-mcp) and [mobile-mcp](https://github.com/mobile-next/mobile-mcp). These tools change quickly, so check their sites for the current state.

Questions

## Before you start.

**Who is Autonom for?**

Teams that build Android, iOS or Flutter apps with an AI coding agent and want the agent to check its work on a running app. The agent brings back screenshots, screen trees, logs and a journal of every step as evidence.

**Does it need an MCP server?**

No. Your agent reads the skills and runs the `autonom` command line, which answers in JSON. An optional MCP wrapper is on the roadmap; it is not shipped.

**Does it work on real devices?**

Autonom is built for the Android emulator and the iOS Simulator. A physical iPhone is not supported: iOS targets come from the Simulator tools alone.

An Android phone connected over adb is treated as a physical device, and support for it is partial. Some commands refuse a phone on purpose: network capture (the proxy listens on your computer alone), location mocking, shutdown, accessibility recovery and snapshots.

**What do I need to install?**

Git and Python 3.11 or later run the command line. Add device tools for what you use: Android platform tools (adb) for Android, a Mac with Xcode for the iOS Simulator (idb is the recommended UI backend there), mitmproxy for network capture. Node.js 20.11 or later is needed only for the Mobile Canvas and for running Autonom's own test suite.

`autonom doctor` lists what is present and the command that installs the rest.

**Is it safe with my app's network traffic?**

Capture is off until you ask for it. Starting the proxy, attaching a device and installing a certificate each need their own flag on every run, plus a typed phrase on an interactive terminal. Consent is never remembered.

The proxy listens on `127.0.0.1`, credentials are masked before anything is written, full bodies are off by default, and your computer's network settings are never changed. Autonom does not bypass certificate pinning. Masking cannot catch every kind of personal data, so use test accounts.

**Does it replace my UI tests?**

No. Your unit, widget and integration tests stay; they are the lower rungs of the evidence ladder. For repeatable device checks, save a flow and run it with `autonom flow run`, or in CI with `autonom ci run`, and export a JUnit report with `autonom report export --format junit`. Maestro flows within Autonom's Maestro Core Profile run directly; anything outside it, such as scripts or JavaScript, is refused with its position in the file.

**What does it cost?**

Nothing. Autonom is open source under the MIT license. It needs no account, sends no usage data or test artifacts to the maintainer, and keeps its evidence on your machine under `~/.autonom/`.

**How do I update it?**

Ask your agent: the `autonom-setup` skill checks for a newer version and refreshes the plugin and the command line. By hand, refresh the plugin with your agent's plugin commands, then update the command line separately with `./scripts/install_cli.sh` from your checkout, or with a release bundle's `install.sh --cli-only`.

Check the result with `autonom version` and `autonom doctor`, then start a new agent session so it loads the new skills.

Install

## Ready in four steps.

Works with Claude Code, Codex, Grok and any agent that loads skills.

### 1. Get the code.

Clone the repository and step into it.

```sh
git clone https://github.com/aiatsuk/autonom
cd autonom
```

### 2. Install it.

A checklist asks which device tools to add. Tick your agents too, and each one gets the skills.

```sh
./install.sh
```

### 3. Ask what this machine can do.

Green means installed, not proven. Anything missing comes with the exact fix.

```sh
autonom doctor
```

### 4. Take the tour.

Start a new agent session so it loads the skills. Then take the guided walk on your device.

```sh
autonom tour
```

### Or, without cloning.

Claude Code and Codex can add the skills as a plugin. Start a new session afterwards so it loads.

- Claude Code

  ```sh
  claude plugin marketplace add aiatsuk/autonom
  claude plugin install autonom@autonom
  ```

- Codex

  ```sh
  codex plugin marketplace add aiatsuk/autonom
  codex plugin add autonom@autonom
  ```

Needs git and Python 3.11 or later. Node 20.11 or later is needed only for the Mobile Canvas and Autonom's own test suite. iOS Simulator targets need a Mac with Xcode. Free under the MIT license. Current version 0.36.1, see the [changelog](https://github.com/aiatsuk/autonom/blob/main/CHANGELOG.md).

[Full install guide](https://autonom.yatsuk.me/docs/install/index.md)

## Run your first check.

Point your agent at a Simulator or an emulator and get back a screenshot and a journal of every step.

- [Your first check](https://autonom.yatsuk.me/docs/first-check/index.md)
- [Browse all docs](https://autonom.yatsuk.me/docs/index.md)