iDeviceTail — wireless iOS/iPadOS log collection

Collect and view logs from your own iPhones/iPads over Wi‑Fi, with no cable during normal operation. One desktop app (Python, cross‑platform) fuses two capture engines into a single live viewer:

Read docs/FEASIBILITY.md first. iOS does not give third‑party software the system‑log firehose. Engine A uses Apple's supported device‑debug channel (lockdown syslog_relay / os_trace_relay, the same one Console.app and log stream use) and therefore inherits Apple's pairing + Developer Mode requirements. Engine B is 100% App‑sandbox legal but only sees its own process. The tool ships both and merges them.

📖 Full step‑by‑step setup + run guide (phone and desktop): docs/GUIDE.md.

Quick start

Windows: double‑click start.bat. First run makes a venv, installs, launches the server and opens the web UI. That's the only "command".

macOS/Linux (or manual):

python -m venv .venv && . .venv/bin/activate     # Windows: .venv\Scripts\activate
pip install -e ".[device]"                        # from a checkout
#   or:  pip install "idevicetail[device]"        # from PyPI
python -m idevicetail serve                        # opens http://localhost:3017 in your browser

Use Python 3.10–3.13 (not 3.14 yet — pymobiledevice3's C‑ext deps have no 3.14 wheels). The app‑log agent (Engine B) works on any 3.10+.

Everything else is buttons in the browser — no more commands:

A CLI still exists for scripting (idevicetail discover | stream | crash-pull | export …) but you never need it for normal use.

Repository layout

iDeviceTail/
├── docs/            Feasibility report, architecture, protocol, compatibility, setup, troubleshooting, test plan
├── desktop/
│   ├── idevicetail/   Python package: discovery, engines, normalizer, bus, store, aiohttp server, CLI
│   │   └── web/     Static log‑viewer UI (no build step)
│   └── tests/       pytest: parsing, framing, dedup, store
├── ios/
│   ├── IDeviceTailKit/     Swift Package: OSLogStore reader, Bonjour, framed TCP client, reconnect
│   └── IDeviceTailAgent/   SwiftUI app that hosts the SDK (XcodeGen project)
├── scripts/         setup / run / pairing helpers (PowerShell + sh)
├── start.bat / stop.bat / hub.json   project-hub integration
└── pyproject.toml

Platform support

macOS:    Full      (Engine A wireless incl. iOS 17.4+ firehose via remoted; Engine B; wireless app install)
Windows:  Partial   (Engine A: full ≤ iOS 17.3 over Wi-Fi, syslog-only for 17.4+ over Wi-Fi; Engine B full)
Linux:    Partial   (same as Windows)

See docs/COMPATIBILITY.md for the capability matrix.

License

MIT (this project). Engine A shells out to pymobiledevice3 (GPL‑3.0) as a separate process; it is an optional dependency you install yourself.