fidelity-ai-workspace/scripts/iphone-photo-inbox/README.md

iPhone Photo Inbox

Local HTTP receiver for sending JPEGs from iPhone Shortcuts into a Mac folder. The transport is intentionally generic: the iPhone uploads a JPEG, and the Mac chooses the destination folder.

Default destination:

ai/inbox/photos/

That default is useful for OpenCode because the images land inside this workspace as raw evidence. For broader use, point the receiver at a neutral folder such as ~/Pictures/iPhone Inbox.

Start the receiver

OpenCode/workspace inbox:

IPHONE_PHOTO_TOKEN="choose-a-token" python3 scripts/iphone-photo-inbox/receiver.py

General-purpose photo inbox:

IPHONE_PHOTO_TOKEN="choose-a-token" \
IPHONE_PHOTO_OUTPUT_DIR="$HOME/Pictures/iPhone Inbox" \
python3 scripts/iphone-photo-inbox/receiver.py

Useful receive modes:

# Show a macOS notification when a photo arrives.
IPHONE_PHOTO_NOTIFY=1 IPHONE_PHOTO_TOKEN="choose-a-token" python3 scripts/iphone-photo-inbox/receiver.py

# Reveal each received photo in Finder.
IPHONE_PHOTO_REVEAL=1 IPHONE_PHOTO_TOKEN="choose-a-token" python3 scripts/iphone-photo-inbox/receiver.py

# Copy each received photo file to the Mac clipboard for pasting into apps.
IPHONE_PHOTO_COPY=1 IPHONE_PHOTO_TOKEN="choose-a-token" python3 scripts/iphone-photo-inbox/receiver.py

These can be combined:

IPHONE_PHOTO_NOTIFY=1 \
IPHONE_PHOTO_COPY=1 \
IPHONE_PHOTO_OUTPUT_DIR="$HOME/Pictures/iPhone Inbox" \
IPHONE_PHOTO_TOKEN="choose-a-token" \
python3 scripts/iphone-photo-inbox/receiver.py

The flags also accept true, yes, or on:

IPHONE_PHOTO_NOTIFY=true IPHONE_PHOTO_COPY=true ...

When these modes are active, the receiver startup log should include:

notifications enabled
clipboard copy enabled

After each upload, it should also print:

notification sent
copied file to clipboard

If those startup lines do not appear, the environment variables were not passed to the running receiver process. If the startup lines appear but the post-upload lines do not, check the printed macOS action failed: error and macOS privacy permissions for Terminal/Codex automation and notifications.

Find the Mac IP address on the current network:

ipconfig getifaddr en0

The iPhone Shortcut should send each JPEG to:

http://MAC_IP:8787/upload?token=choose-a-token

Shortcut shape

Fastest reliable flow

Put this Shortcut on the Home Screen, Lock Screen, Action Button, or Back Tap. This is the most reliable "take photo and send immediately" flow because the Shortcut owns the capture and upload sequence.

Use this when you want the camera itself to be the capture flow:

Take Photo
    Show Camera Preview: On
Get Contents of URL
    URL: http://MAC_IP:8787/upload?token=choose-a-token
    Method: POST
    Request Body: File
    File: Photo
Show Notification
    Sent to Mac photo inbox

On the tested iPhone flow, Take Photo already produces a JPEG, so the conversion step is intentionally omitted for the fastest path.

Existing Photos flow

Use this when you want to send existing images from Photos:

Receive Images and Media from Share Sheet
Repeat with Each Item in Shortcut Input
    Convert Image
        Image: Repeat Item
        Format: JPEG
    Get Contents of URL
        URL: http://MAC_IP:8787/upload?token=choose-a-token
        Method: POST
        Request Body: File
        File: Converted Image
End Repeat
Show Notification
    Sent to Mac photo inbox

Semi-automatic Camera.app flow

iOS does not expose a clean "new photo was taken" automation trigger. The closest option is a Personal Automation:

When Camera is Closed
    Get Latest Photos
        Include Screenshots: Off
        Limit: 1
    Convert Image
        Format: JPEG
    Get Contents of URL
        URL: http://MAC_IP:8787/upload?token=choose-a-token
        Method: POST
        Request Body: File
        File: Converted Image

This is convenient, but it can resend the latest photo if you open and close Camera without taking a new one. Prefer the Shortcut-owned camera flow when duplicates would be annoying.

Usage profiles

OpenCode analysis:

• Use the default ai/inbox/photos/ destination.
• Reference the received file directly from this workspace.
• Treat received files as raw evidence until reviewed.

Mattermost / Jeff:

• Use a neutral destination such as ~/Pictures/iPhone Inbox.
• Attach the latest received JPEG from Mattermost on the Mac.
• Keep the same Shortcut and URL; only the Mac receiver destination changes.

General capture:

• Use the neutral destination when the photo is not specifically workspace evidence.
• Keep JPEG validation enabled in the receiver so downstream tools get a predictable format.