# Phone Harness Documentation

> Technical docs for phone-harness: the CLI, pre-imported helpers, dual input backends, connection gates, OCR, and diagnostics that drive a real iPhone through macOS iPhone Mirroring.

This is a Grok-Wiki source-grounded repository documentation set. Use the complete Markdown link when an agent needs the full repo context.

## Context Links

- [Complete Markdown docs](https://grok-wiki.com/public/docs/shawnpana-phone-harness-bf80173a2a2e/llms-full.txt)
- [Complete Markdown alias](https://grok-wiki.com/public/docs/shawnpana-phone-harness-bf80173a2a2e.md)
- [Human interactive docs](https://grok-wiki.com/public/docs/shawnpana-phone-harness-bf80173a2a2e)
- [GitHub repository](https://github.com/ShawnPana/phone-harness)

## Repository

- Repository: ShawnPana/phone-harness

- Generated: 2026-08-10T20:26:54.459Z
- Updated: 2026-08-10T21:10:47.530Z
- Runtime: Grok CLI
- Format: Documentation
- Pages: 17

## Pages

- [Overview](https://grok-wiki.com/public/docs/shawnpana-phone-harness-bf80173a2a2e/pages/01-overview.md): What phone-harness exposes, who it is for, runtime assumptions (macOS Sequoia+, iPhone Mirroring, real phone), and the first docs routes to follow.
- [Installation](https://grok-wiki.com/public/docs/shawnpana-phone-harness-bf80173a2a2e/pages/02-installation.md): Prerequisites, clone to ~/.phone-harness, pyobjc and editable pip install, PATH command, skill registration, and verification with phone-harness --doctor.
- [Quickstart](https://grok-wiki.com/public/docs/shawnpana-phone-harness-bf80173a2a2e/pages/03-quickstart.md): First successful script: check connection state, print screen_info, run a short stdin Python block with pre-imported helpers, and read the success signal.
- [Connection and session states](https://grok-wiki.com/public/docs/shawnpana-phone-harness-bf80173a2a2e/pages/04-connection-and-session-states.md): connection_state values ready, blocked, no-window, not-running; ensure_mirroring gates; blocked interstitial markers; and why reconnect is a user physical action.
- [Coordinates, capture, and OCR](https://grok-wiki.com/public/docs/shawnpana-phone-harness-bf80173a2a2e/pages/05-coordinates-capture-and-ocr.md): Global screen-point space, window bounds vs image pixels, capture return shape, Vision OCR boxes with confidence and tap-ready centers, and why coordinates must not be cached.
- [Input backends](https://grok-wiki.com/public/docs/shawnpana-phone-harness-bf80173a2a2e/pages/06-input-backends.md): Default background backend (SkyLight event records, no focus steal) versus classic mirror backend (CGEvent HID + activate); selection via PHONE_HARNESS_BACKGROUND and automatic fallback.
- [Consent and limits](https://grok-wiki.com/public/docs/shawnpana-phone-harness-bf80173a2a2e/pages/07-consent-and-limits.md): When not to use the phone, outward-facing and irreversible actions that require user consent, and hard product limits (one session, no multi-touch, DRM black frames, keycode typing).
- [See, act, and verify](https://grok-wiki.com/public/docs/shawnpana-phone-harness-bf80173a2a2e/pages/08-see-act-and-verify.md): OCR-first reading, tap and tap_text, wait_stable, screenshot for unlabeled icons, and the capture-as-ground-truth verification loop after every action.
- [Navigate apps and type text](https://grok-wiki.com/public/docs/shawnpana-phone-harness-bf80173a2a2e/pages/09-navigate-apps-and-type-text.md): home, app_switcher, open_app via Spotlight, press key combos, type_text US keycode constraints, and Home Screen tap_icon versus in-app tap_text.
- [Scroll and collect lists](https://grok-wiki.com/public/docs/shawnpana-phone-harness-bf80173a2a2e/pages/10-scroll-and-collect-lists.md): scroll_screen movement detection, scroll_until predicates, scroll_collect de-dup extraction, wheel versus flick behavior, settle windows, and stop reasons reached-end and max-scrolls.
- [Extend agent helpers](https://grok-wiki.com/public/docs/shawnpana-phone-harness-bf80173a2a2e/pages/11-extend-agent-helpers.md): Edit agent-workspace/agent_helpers.py for task-specific primitives, PH_AGENT_WORKSPACE override, auto-load into the script namespace, and the tap_icon Home Screen pattern.
- [Register as an agent skill](https://grok-wiki.com/public/docs/shawnpana-phone-harness-bf80173a2a2e/pages/12-register-as-an-agent-skill.md): phone-harness skill output, Claude Code and Codex skill install paths, trigger text, and re-sync after pulls so the agent auto-reaches for phone control.
- [CLI reference](https://grok-wiki.com/public/docs/shawnpana-phone-harness-bf80173a2a2e/pages/13-cli-reference.md): phone-harness entry points: stdin Python exec with helpers in scope, --doctor and doctor, skill, help flags, usage errors when args or TTY lack a script, and the ./phone-harness checkout launcher.
- [Helpers API](https://grok-wiki.com/public/docs/shawnpana-phone-harness-bf80173a2a2e/pages/14-helpers-api.md): Pre-imported public helpers: session, capture, ocr, gestures, scroll family, navigation, timing, and re-exported backend primitives with signatures, defaults, return shapes, and raised errors.
- [Environment variables](https://grok-wiki.com/public/docs/shawnpana-phone-harness-bf80173a2a2e/pages/15-environment-variables.md): PHONE_HARNESS_BACKGROUND default and falsey values, PH_AGENT_WORKSPACE path override, temp capture directory under phone-harness, and how backend selection falls back when SkyLight load fails.
- [Doctor diagnostics](https://grok-wiki.com/public/docs/shawnpana-phone-harness-bf80173a2a2e/pages/16-doctor-diagnostics.md): Ordered --doctor ladder: pyobjc, Accessibility, Screen Recording, app installed, running, window, capture size, Vision OCR; exit codes; and the note that fresh machines may need extra prompts.
- [Troubleshooting](https://grok-wiki.com/public/docs/shawnpana-phone-harness-bf80173a2a2e/pages/17-troubleshooting.md): Failure modes and recovery: blank capture after Screen Recording grant, window not found, silent taps without Accessibility or focus, blocked iPhone in Use, Home Screen label misses, and type_text field focus.

## Source Files

- `agent-workspace/agent_helpers.py`
- `install.md`
- `phone-harness`
- `pyproject.toml`
- `README.md`
- `SKILL.md`
- `src/phone_harness/admin.py`
- `src/phone_harness/background.py`
- `src/phone_harness/helpers.py`
- `src/phone_harness/mirror.py`
- `src/phone_harness/ocr.py`
- `src/phone_harness/run.py`