Why wrap ADB at all
ADB is capable and its surface is enormous. The commands you need occasionally are the ones you will never remember, so they end up pasted from a text file with the wrong flags for your device.
phonesurgeon collects those operations — around 200 of them — into one interface with consistent naming, real help text, and explicit confirmation on anything destructive.
What it covers
- Device & state: discovery, properties, battery and thermal state, connectivity.
- Packages: list, inspect, install, uninstall, disable, clear data, dump permissions.
- Files: push, pull, and bulk transfer with progress.
- Diagnostics: filtered logcat, bug reports, screen capture and recording.
- Input: scripted taps, swipes, key events, and text entry.
The guardrail model
Every operation carries a class:
| Class | Behaviour |
|---|---|
| Read | Runs immediately. Cannot change device state. |
| Write | Runs immediately, reports exactly what changed. |
| Destructive | Requires explicit confirmation naming the target. |
The class is metadata on the operation, not a check bolted on at the call site — so a new destructive operation is guarded the moment it is registered.
Design decisions
Never guess the device
With more than one device attached, the tool asks. Silently picking the first serial is how you wipe the wrong phone.
Parse output properly
ADB output formats vary between Android versions. Parsing lives in one layer with per-version handling, so the operations themselves stay simple.
Getting started
git clone https://github.com/thecrewx/phonesurgeon
cd phonesurgeon
pip install -r requirements.txt
adb devices
python -m phonesurgeon devices
python -m phonesurgeon packages --third-party