Metadata-Version: 2.4
Name: unjiggle
Version: 0.3.2
Summary: AI-powered iPhone home screen organizer. One command to scan, score, and fix your layout over USB.
Author: chungty
License: GPL-3.0-or-later
Project-URL: Homepage, https://unjiggle.com
Project-URL: Repository, https://github.com/chungty/unjiggle
Project-URL: Issues, https://github.com/chungty/unjiggle/issues
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pymobiledevice3>=9.0.0
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.0
Requires-Dist: jinja2>=3.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: pillow>=10.0
Provides-Extra: ai
Requires-Dist: anthropic>=0.40.0; extra == "ai"
Requires-Dist: openai>=1.0; extra == "ai"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Dynamic: license-file

# Unjiggle

**Your iPhone home screen is a mess. You know it. You've given up fixing it. Unjiggle fixes it for you.**

Unjiggle is an AI-powered CLI that reads your iPhone home screen, scores your organization, roasts your app collection, writes obituaries for your dead apps, and generates share cards you'll actually want to post.

<p align="center">
  <img src="assets/cli-demo.png" width="600" alt="unjiggle go — one command to scan, score, and analyze your iPhone">
</p>

## Quick Start

```bash
pip install unjiggle
```

Connect your iPhone via USB, then:

```bash
unjiggle go
```

One command. It scans your phone, scores your organization, calculates your swipe tax, and generates a share card that auto-copies to your clipboard. Cmd+V to paste into iMessage, Twitter, or Instagram.

## Share Cards

Every feature generates a 1080x1350 share card that copies to your clipboard automatically. No screenshots needed — just Cmd+V.

<p align="center">
  <img src="assets/share-card.png" width="400" alt="Unjiggle share card — The Organized Maximalist, score 70/100">
</p>

## Features

### Core (no API key needed)

| Command | What it does |
|---------|-------------|
| `unjiggle go` | Full experience: scan, score, archetype, swipe tax, share card |
| `unjiggle swipetax` | How many unnecessary swipes your layout costs per year |
| `unjiggle scan` | See your layout color-coded by category |
| `unjiggle score` | Organization score (0-100) with breakdown |
| `unjiggle demo` | Try it without a phone — see what the output looks like |

### Viral features (works without API key, better with one)

| Command | What it does |
|---------|-------------|
| `unjiggle mirror` | Personality roast from your app collection |
| `unjiggle obituary` | Eulogies for your dead apps |

These generate share cards with or without an API key. With Claude or GPT, the roasts are funnier and more personal. Without, you get a solid rule-based analysis.

### AI-powered (needs API key)

| Command | What it does |
|---------|-------------|
| `unjiggle analyze` | Deep AI observations (Claude or GPT-4.1) |
| `unjiggle suggest` | Interactive walkthrough — apply changes step by step |
| `unjiggle suggest --apply-all` | Just Fix It mode — apply everything at once |

### Safety

| Command | What it does |
|---------|-------------|
| `unjiggle safety-test` | Read the layout and verify a backup without changing the phone |
| `unjiggle safety-test --write-roundtrip` | Offer a write test that can change icons; requires confirmation |
| `unjiggle backup` | Save current layout |
| `unjiggle restore` | List backups; pass a file to attempt a restore |

### Safety update in 0.3.2

Earlier versions of `safety-test` sent the layout back to the iPhone despite saying
the test changed nothing. Sending even an unchanged layout can make iOS add or move
icons. The default test now only reads the phone and saves a backup.

- A write test requires `--write-roundtrip` and a separate yes/no confirmation that
  defaults to No. It is not needed before using Unjiggle.
- Preparing to apply changes no longer runs an extra test write.
- If the layout changes while a backup is being checked, Unjiggle stops and keeps
  the original backup. New verified backups do not overwrite files from the same second.
- Restore saves the phone's current layout first. If the phone does not match the
  requested backup afterward, the command reports failure and exits with an error.
  It does not retry or try another restore automatically.
- Restore refuses completely empty layouts and unsupported backup formats rather
  than sending them to the phone. Layouts containing only widgets are supported.

These changes do not establish a fix for icons returning on iOS 27, or a safe way
to recover folders lost after resetting the Home Screen. If a test or restore has
already changed your layout unexpectedly, stop further attempts and keep your backups.
Backup files contain app and folder names; share them privately when seeking help.

## Requirements

- **macOS** (USB communication with iPhone)
- **iPhone connected via USB** with "Trust This Computer" accepted
- **Python 3.10+**
- **API key** (optional): set `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` for AI features. Core features and share cards work without one.

## How It Works

Unjiggle uses [pymobiledevice3](https://github.com/doronz88/pymobiledevice3) to communicate with your iPhone's SpringBoard services over USB. It reads the `IconState` (your home screen layout), enriches it with App Store metadata, and generates observations and layout suggestions.

On macOS 12-15, it can also read Screen Time data from `knowledgeC.db` for real app usage stats (last opened, daily opens). On newer macOS versions, it falls back to positional heuristics.

Share cards render to PNG via Chrome headless and auto-copy to your macOS clipboard.

Earlier device testing used an iPhone 16 Pro on iOS 26; it does not establish safety
on other iOS versions. Applying or restoring a layout can add or move icons. A
verified backup is not a guarantee that a restore will succeed, and an immediate
match does not prove the layout will stay the same after a reboot.

## GUI Coming Soon

A native Mac app with live preview, drag-and-drop editing, animated before/after transformations, and a slider to control aggressiveness is in development.

**Sign up for early access:** [unjiggle.com](https://unjiggle.com)

## License

GPL-3.0 (matching pymobiledevice3)
