iPhone Doctor

Automated iPhone performance diagnostics via USB. One command to find out why your iPhone is lagging, stuttering, or draining battery.

What It Detects

• Apple Intelligence drain -- on-device ML processes consuming excessive CPU/memory
• Memory pressure -- Jetsam kills (iOS forcefully terminating apps)
• CPU resource violations -- processes exceeding CPU time limits
• UI freezes -- watchdog timeout kills (0x8BADF00D)
• Crash frequency -- apps crashing repeatedly
• Battery health -- cycle count, capacity degradation
• Storage pressure -- low disk space causing slowdowns
• Safari instability -- WebKit crash patterns

Installation

pip install iphonedoctor

Or install from source:

git clone https://github.com/AmitSubhash/iphonedoctor.git
cd iphonedoctor
pip install -e .

Prerequisites

• macOS (required -- uses libimobiledevice)
• Homebrew (for auto-installing libimobiledevice)
• Python 3.10+
• iPhone connected via USB cable with "Trust This Computer" accepted

The tool will auto-install libimobiledevice via Homebrew if not already present.

Usage

# Run full diagnostics
iphonedoctor

# Output as JSON (for piping to other tools)
iphonedoctor --json

# Keep crash data after analysis (default: cleaned up)
iphonedoctor --keep-crashes

# Skip auto-install prompt
iphonedoctor --no-install

# Show version
iphonedoctor --version

How It Works

1. Checks/installs libimobiledevice via Homebrew
2. Detects your iPhone via USB
3. Reads device info, battery health, and storage
4. Pulls crash reports (.ips files) from the device
5. Parses and classifies each report (Jetsam, CPU violation, watchdog, crash)
6. Runs analyzers to find patterns across all reports
7. Generates prioritized, actionable fix recommendations
8. Renders a color-coded terminal report

Example Output

iPhone Doctor v0.1.0

  Found: iPhone 16 Pro (amit;))

---- iPhone Doctor -- Diagnostic Report ----

+-- Device -----+
| amit;)         |
| iPhone 16 Pro  |
| iOS 26.2.1     |
+----------------+

+-- Battery ----+
| Charge:  29%  |
| Health:  100% |
| Cycles:  260  |
+---------------+

+-- Analysis Summary --+
| Total Reports    175 |
| Jetsam Kills      14 |
| CPU Violations    18 |
| Watchdog Kills     4 |
| AI Events         32 |
+-----------------------+

[!!] #1: Apple Intelligence draining resources [HIGH]
  Settings > Apple Intelligence & Siri > Turn off Apple Intelligence
  ...

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Lint
ruff check src/
ruff format --check src/

License

MIT