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

iPhone Photo Inbox

Local HTTP receiver for sending JPEGs from iPhone Shortcuts into Mac inboxes. The Shortcut sends a profile, and the Mac decides the destination folder and clipboard behavior.

Profiles

opencode

• Saves to ai/inbox/photos/
• Copies a terminal-safe path to the clipboard
• Best for pasting into OpenCode running in a terminal

mattermost

• Saves to ~/Pictures/iPhone Inbox
• Copies the image data to the clipboard
• Best for pasting directly into Mattermost

general

• Saves to ~/Pictures/iPhone Inbox
• Does not modify the clipboard
• Useful for plain capture

All profiles show a macOS notification by default.

Start the receiver

Recommended:

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

The receiver listens on:

http://MAC_IP:8787/upload

Find the Mac IP address on the current network:

ipconfig getifaddr en0

If that does not return an IP, use:

ifconfig

Shortcut config

Use a Dictionary near the top of the Shortcut:

mac_ip: 192.168.11.186
port: 8787
token: choose-a-token
profile: opencode

Build the URL from the dictionary:

http://[mac_ip]:[port]/upload?token=[token]&profile=[profile]

Use profile: opencode when the next paste target is OpenCode. Use profile: mattermost when the next paste target is Mattermost.

Camera shortcut

Dictionary
    mac_ip: 192.168.11.186
    port: 8787
    token: choose-a-token
    profile: opencode

Text
    http://[mac_ip]:[port]/upload?token=[token]&profile=[profile]

Take Photo
    Show Camera Preview: On

Get Contents of URL
    URL: Text
    Method: POST
    Request Body: File
    File: Photo

Show Notification
    Sent to [profile]

On the tested iPhone flow, Take Photo already produces a JPEG, so no conversion step is needed.

Existing photos shortcut

Use this when sending 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]:[port]/upload?token=[token]&profile=[profile]
        Method: POST
        Request Body: File
        File: Converted Image
End Repeat
Show Notification
    Sent to [profile]

Overrides

Profile folders:

IPHONE_PHOTO_OPENCODE_DIR="/path/to/opencode/photos"
IPHONE_PHOTO_MATTERMOST_DIR="$HOME/Pictures/iPhone Inbox"
IPHONE_PHOTO_GENERAL_DIR="$HOME/Pictures/iPhone Inbox"

Global folder override for all profiles:

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

Default profile when the URL does not include profile=:

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

Clipboard override for all profiles:

IPHONE_PHOTO_CLIPBOARD=image
IPHONE_PHOTO_CLIPBOARD=terminal-path
IPHONE_PHOTO_CLIPBOARD=path
IPHONE_PHOTO_CLIPBOARD=file
IPHONE_PHOTO_CLIPBOARD=none

Other useful options:

python3 scripts/iphone-photo-inbox/receiver.py --no-notify
python3 scripts/iphone-photo-inbox/receiver.py --reveal

Troubleshooting

Startup should print each active profile:

profile opencode: dir=... clipboard=terminal-path notify=True reveal=False
profile mattermost: dir=... clipboard=image notify=True reveal=False

After upload, expect:

notification sent
clipboard mode applied: terminal-path
saved ... profile=opencode

For Mattermost, expect:

clipboard mode applied: image

If files arrive but clipboard/notifications do not behave as expected, check:

• The Shortcut URL includes the intended profile=.
• The receiver log shows the expected profile.
• macOS Focus/Do Not Disturb is not hiding notifications.
• Terminal/Codex has permission for AppleScript automation if macOS prompts.