Documentation

TetherShot · native macOS utility · MIT licensed

Overview

TetherShot is a native macOS app with an optional menu-bar controller. It captures pixel-perfect screenshots of an iPhone and saves them to a folder you choose (optionally copying each to your clipboard). It supports two capture paths:

• USB — a trusted, cabled iPhone is exposed to macOS as a screen source via AVFoundation. Instant, no extra setup.
• Wi-Fi — cable-free capture over your local network using Apple's developer-services tunnel (powered by pymobiledevice3). Requires a one-time setup.

TetherShot opens as a compact Mac app with an optional menu-bar control. Closing its window removes the Dock icon while capture, updates, and the global hotkey keep running in the background.

Requirements

• macOS 14 (Sonoma) or later — developed and tested on macOS 26 (Tahoe).
• Xcode Command Line Tools — only needed to build from source: xcode-select --install.
• Node.js 18+ — only needed for npm installation.
• An iPhone you can set to Trust This Computer.
• For Wi-Fi: the iPhone and Mac on the same network, plus pymobiledevice3.

Install

For a normal Mac install, use the verified Homebrew Cask or download the signed and notarized universal DMG. Developers can use npm for the CLI and source-built workflow.

brew install --cask aopv/tap/tethershot

open https://github.com/aopv/TetherShot/releases/latest

npm install -g tethershot   # links the CLI (and builds the app)
tethershot install         # ensure the app is in ~/Applications
tethershot                 # launch it

Note: npm 11+ blocks postinstall scripts by default, so if the app isn't built after npm install, the explicit tethershot install step always does it.

From source

git clone https://github.com/aopv/TetherShot.git
cd TetherShot
./build.sh             # compiles + packages TetherShot.app
open .build/TetherShot.app

First capture (USB)

1. Connect your iPhone with a cable and tap Trust This Computer (unlock if prompted).
2. Click the TetherShot icon in the menu bar.
3. Your phone appears as 📸 <name> (USB) — click it. (Use Refresh Devices if it's not listed yet.)
4. The first capture triggers a one-time Camera permission prompt — allow it. (The iPhone screen rides the camera privacy bucket; your Mac camera is never used.)
5. The PNG lands in your folder (default ~/Pictures/TetherShot) and, if enabled, on your clipboard.

Wi-Fi capture

Wireless capture uses a root tunnel daemon (tunneld) that keeps a RemoteXPC tunnel alive so captures need no sudo. One-time setup:

# 1 · install pymobiledevice3 (the engine)
pip3 install -U pymobiledevice3

# 2 · install the tunnel service (asks for admin password once)
tethershot setup-wifi

# 3 · with the iPhone connected over USB once:
#     enable Developer Mode (Settings ▸ Privacy & Security)
pymobiledevice3 lockdown wifi-connections --state on

After that you can unplug. While the iPhone and Mac are on the same Wi-Fi, the menu shows it as (Wi-Fi) and captures are pixel-perfect — even when the phone is locked. The tunnel daemon is discovered automatically.

Why not AirPlay mirroring? On macOS Tahoe, a mirrored iPhone window blacks out whenever any screen-capture context is active, so TetherShot uses the developer-services path instead — it captures the device's own framebuffer regardless of transport.

CLI

tethershot            # launch the app
tethershot install    # build & install to ~/Applications
tethershot update     # update to the latest published version
tethershot setup-wifi # install the Wi-Fi tunnel service
tethershot uninstall  # remove the app
tethershot version    # print the installed version

Options

All options live in the menu and persist across launches:

• Copy to Clipboard (on by default) — also place each capture on the clipboard, ready to paste.
• Organize by Device — save into a per-device subfolder.
• Choose Folder… — pick any destination; the choice is remembered.
• Quick Capture Device — choose one iPhone for the global hotkey, or keep the default “All connected devices.” The selection persists across launches.
• Quick capture — press ⌘⇧7 anywhere to capture the saved target without opening the menu.
• Launch at Login — keep TetherShot in your menu bar across reboots.
• Auto-check for Updates — quietly check GitHub for newer signed releases.

Updating

Use Check for Updates… in the menu, then Update & Relaunch. TetherShot downloads the signed and notarized universal DMG, verifies its GitHub SHA-256 digest and Developer ID signature, replaces the current installation in place, and relaunches. Node.js and Xcode are not required for normal updates. CLI users can still update the optional command separately:

tethershot update

Heads-up: the from-source build is ad-hoc signed, which isn't stable across rebuilds, so an update may re-trigger the one-time Camera permission prompt.

Troubleshooting

The iPhone isn't listed

Make sure it's unlocked and trusted, then hit Refresh Devices. Over USB it must appear as a screen source; a wireless-only connection surfaces as a camera, which TetherShot ignores by design.

“Capturing…” hangs or errors

Confirm the iPhone is unlocked. For Wi-Fi, ensure the tunneld service is running (tethershot setup-wifi installs it) and both devices share a network/subnet.

Camera permission blocked

Enable TetherShot under System Settings ▸ Privacy & Security ▸ Camera, then capture again.

Uninstall

tethershot uninstall                 # removes the app
npm uninstall -g tethershot         # removes the CLI
bash scripts/uninstall-tunneld.sh   # removes the Wi-Fi service

Questions or bugs? Open an issue on GitHub.