# Install

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

One script puts the `autonom` command line on your PATH and gives your agent its skills. Then `autonom doctor` says what works on this machine and how to fix the rest.

**Try it**

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

## How it works

Four steps in a terminal. You need git, Python 3.11 or later and Node 20.11 or later.

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. In Claude Code:

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

In Codex:

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

Autonom comes in three layers, and only the first is required. The command line is always installed. Device tools and agent skills are checkboxes you pick.

![The install script at the top branches into three boxes: the autonom command line, marked always, and device tools and agent skills, marked opt-in. All three lead down to autonom doctor.](https://autonom.yatsuk.me/docs/install/layers.svg)

Only the command line is required; the doctor reports what the rest adds.

On a terminal, the script preselects what the machine can plausibly use, such as a `claude` or `codex` command line it finds. Without a terminal it never prompts: no flags means the command line only.

The command line is one Python script that uses only the standard library. The installer links it into `~/.local/bin`, so there is no virtualenv, no pip and no build step.

Skills install per agent: Claude Code and Codex through their plugin marketplaces, Grok and any other agent through a skills folder. Each device tool is found at run time and unlocks one capability, so you can add it later.

## Examples

### Install for one agent without the checklist

**Goal:** the command line, the device tools and the skills for Claude Code in one pass, with no questions.

1. **Name what you want.** It fetches adb, mitmproxy and idb through brew, pipx or apt-get, then adds the skills.

   ```sh
   ./install.sh --tools --claude
   ```

2. **Start a new agent session.** Claude Code loads plugins when a session starts.

3. **Check the command line.** It answers in JSON, like every Autonom command.

   ```sh
   autonom version
   ```

You should see the name and the version you installed.

*Output of autonom version*

```
{
  "name": "autonom",
  "version": "0.36.1"
}
```

**What to look at.** Any answer means `autonom` is on your PATH. If the shell cannot find it, add `~/.local/bin` to your PATH: the installer prints the line to add.

### Find out what this machine can do

**Goal:** know which platforms work before your agent picks a target.

1. **Ask the doctor.** Each capability says whether it is ready and what it needs.

   ```sh
   autonom doctor
   ```

2. **Gate a pipeline on it.** Strict mode exits 1 when something is missing.

   ```sh
   autonom doctor --strict
   ```

You should see one entry per capability, each with `ready` and what it needs.

*Output of autonom doctor: example output; your values will differ*

```
…
  "capabilities": {
    "android": {
      "ready": true,
      "needs": "adb"
    },
    …
    "ios_hid": {
      "ready": false,
      …
      "axe_ready": true,
…
```

**What to look at.** `ios_hid` is not ready on this Mac, which runs Xcode 27 with an older idb companion. `axe_ready` is true, so taps still work through AXe, as the next example shows.

### Fix taps on Xcode 27

**Goal:** the screen reads, but every tap, swipe and typed string fails with [`ios_hid_framework_missing`](https://autonom.yatsuk.me/docs/safety/index.md#ios_hid_framework_missing); make input work again.

Xcode 27 moved SimulatorKit, and an idb companion built before that still looks in the old place. Upgrade the companion, or install AXe.

1. **Confirm the cause.** The doctor shows `ios_hid` not ready next to a working `ios_tree`.

   ```sh
   autonom doctor
   ```

2. **Trust the companion's formula.** Homebrew refuses the companion from an untrusted tap, and its error names neither the tap nor the fix.

   ```sh
   brew trust --formula facebook/fb/idb-companion
   ```

3. **Upgrade the companion.** A current build finds SimulatorKit where Xcode 27 put it.

   ```sh
   brew update && brew upgrade idb-companion
   ```

4. **Upgrade its client.** The idb client and the companion move together.

   ```sh
   pipx upgrade fb-idb
   ```

5. **Or install AXe instead.** It drives the Simulator's input on its own, whatever the companion's age.

   ```sh
   brew install cameroncooke/axe/axe
   ```

6. **Run the doctor again.** It names the backend input now uses.

You should see the input backend, and each prerequisite with its fix.

*Output of autonom doctor after the fix: example output; your values will differ*

```
…
  "ios": {
    …
    "hid_backend": "axe"
  },
  "checks": [
    …
    {
      "name": "idb_companion_hid",
      "ok": false,
      …
      "fix": "brew update && brew upgrade idb-companion (and pipx upgrade fb-idb)"
```

**What to look at.** `hid_backend` is `axe`: the screen is still read through idb, and input goes through AXe. This Mac took the AXe route, so `idb_companion_hid` still names the upgrade.

### Take the tour

**Goal:** see what Autonom has and the walk it offers on this machine.

1. **Read the overview.** In a terminal it first prints the overview as text and offers the walk; your agent gets JSON.

   ```sh
   autonom tour
   ```

2. **Walk it on a device.** It walks three screens into Settings and writes an HTML report, as [Your first check](https://autonom.yatsuk.me/docs/first-check/index.md#setup-tour) shows.

   ```sh
   autonom tour --run
   ```

You should see the overview, and the walk proposed for a running emulator.

*Output of autonom tour*

```
{
  "ok": true,
  "mode": "overview",
  …
  "proposal": {
    "available": true,
    …
    "title": "Settings → Network & internet → Internet",
    …
    "run_command": "autonom tour --run --platform android --target emulator-5554"
  }
}
```

**What to look at.** `run_command` is the exact walk the tour offers, on the emulator it found running.

### Reproduce these outputs

The version and tour outputs come from Autonom's fake devices, run as below from the root of an Autonom checkout at tag v0.36.1 (commit ca2a280) in bash or zsh. The doctor reports the tools of the machine it runs on, so its outputs above are examples from one Mac.

*Script that reproduces the outputs*

```sh
export AUTONOM_HOME=/tmp/install/.autonom AUTONOM_EMULATOR=tests/fakes/fake_emulator.py
unset AUTONOM_FAKE_STATE
python3 scripts/autonom.py version
python3 scripts/autonom.py --adb tests/fakes/fake_adb.py --simctl tests/fakes/fake_simctl.py --idb tests/fakes/fake_idb.py tour
```

## Good to know

- **Green means installed, not proven.** The doctor reports what is on the machine. Only a real run on a target proves a capability works.

- **The doctor exits 0 even when tools are missing.** A diagnostic that fails is useless in a pipeline. Pass `--strict` when a missing tool should fail the job.

- **fb-idb breaks on Python 3.14.** Every idb call then dies with “There is no current event loop”. Reinstall it on an older interpreter:

  ```sh
  pipx reinstall fb-idb --python /opt/homebrew/opt/python@3.12/bin/python3.12
  ```

- **A path override can hide a tool.** The doctor lists every active `AUTONOM_*` override and warns with [`override_path_missing`](https://autonom.yatsuk.me/docs/safety/index.md#override_path_missing) when one points at a binary that does not exist.

- **scrcpy is optional, and only 4.1 counts.** It gives [Mobile Canvas](https://autonom.yatsuk.me/docs/canvas/index.md) the device's own video on Android. `./install.sh --tools` does not add it, and the doctor reports it under `optional_tools.scrcpy` without failing `--strict`. On a Mac:

  ```sh
  brew install scrcpy
  ```

- **Claude Code runs a cached copy of the plugin.** After the source changes, update it, then start a new session:

  ```sh
  claude plugin update autonom@autonom
  ```

- **Nothing lands in your project.** [Sessions](https://autonom.yatsuk.me/docs/sessions/index.md) live in `~/.autonom/sessions/`, [app memory](https://autonom.yatsuk.me/docs/memory/index.md) in `~/.autonom/apps/`, and machine state in `~/.local/state/autonom/`. Set `AUTONOM_HOME` to move all of it under one root.

- **Session folders are sensitive.** They can hold screenshots, logs and captured traffic. Delete them when an investigation ends.

## Reference

| Command | What it does |
| --- | --- |
| `./install.sh` | Opens a checklist of device tools, Claude, Codex and Grok. The command line is always installed. |
| `./install.sh --all` | Installs everything without asking. |
| `./install.sh --tools --claude` | Installs any subset. Names such as `claude codex` work too. |
| `./install.sh --cli-only` | Installs only the `autonom` command line. |
| `autonom version` | Prints the installed version. |
| `autonom doctor` | Reports tools, capabilities, leftover processes and active overrides. |
| `autonom doctor --strict` | The same, and exits 1 when something is missing. |
| `autonom tour` | Shows what Autonom has, the usual workflow and this machine's targets. |
| `autonom tour --run` | Walks three screens into Settings and writes an HTML report. |

**Advanced options**

| Command | What it does |
| --- | --- |
| `./install.sh --link ~/.my-agent/skills` | Also links the skills into any skill folder. `--copy` makes a snapshot instead. |
| `./install.sh --prefix /opt/autonom` | Sets the bundle home, `~/.local/share/autonom` by default. |
| `./scripts/install_cli.sh` | Links only `autonom` into `~/.local/bin`. `--copy` writes a launcher script instead. |
| `./scripts/install_skills.sh grok` | Installs the skills for Grok. |
| `./scripts/install_skills.sh --link /path/to/agent/skills` | Links the skills into any agent that loads a folder of `SKILL.md` files. |
| `./scripts/run_checks.sh` | Runs Autonom's own checks. They need no Flutter, Android SDK, Xcode, idb or mitmproxy. |

## Android and iOS differences

What each platform needs before your agent can use it.

| To use | Android | iOS Simulator |
| --- | --- | --- |
| Session, screenshot, logs, deep links | adb from platform-tools | Xcode |
| Accessibility tree | adb | idb and its companion, or the bundled XCUITest runner with full Xcode |
| Tap, swipe, type, keys | adb | idb, or AXe on Xcode 27 |
| Network capture | mitmproxy | mitmproxy |
| Mobile Canvas video | scrcpy 4.1, optional; without it, ffmpeg or screenshots | idb_companion; without it, screenshots |

iOS targets need a Mac with Xcode. An iOS target on another Mac is reachable through its idb companion. The Android SDK and Flutter are needed only when a domain skill works on a real project.

## Next steps

Autonom is installed, and the doctor says what works on this machine.

- [Your first check](https://autonom.yatsuk.me/docs/first-check/index.md): Point your agent at a target and get back screenshots and a journal.
- [Sessions and targets](https://autonom.yatsuk.me/docs/sessions/index.md): Own one device and read every step back.
- [Skills and routing](https://autonom.yatsuk.me/docs/skills/index.md): See which skills your agent loads, and when.