photo-alchemy

Transform any photo into surrealist AI art. Uses Claude to write a story about your photo, then Gemini generates a reimagined version in one of 35+ visual st...

Security Scan

The skill's instructions broadly match its stated purpose (transforming photos via Claude + Gemini) but contain multiple coherence and risk issues: the registry metadata omits required API keys/paths, the README instructs a remote curl | sh installer, it stores API keys in a local SQLite DB, and it reads/writes your Apple Photos (including face-detection names) and can schedule recurring runs — all of which merit caution.

Purpose & Capability

The SKILL.md clearly requires Anthropic and Google Gemini API keys and integrates deeply with macOS Photos and launchd, which is coherent with the described functionality. However, the registry metadata declares no required env vars or config paths — that omission is inconsistent and misleading. Asking for Photos access, face-detection names, and the ability to write back to albums fits the feature set but should have been declared up-front.

Instruction Scope

The runtime instructions direct the agent to: read macOS Photos albums (including face-detection names/people), resize images, send images to external APIs (Anthropic/Claude and Google/Gemini), write generated images back into Photos shared albums, write a local SQLite DB (~/.imagemine.db) containing run metadata and saved API keys, and optionally create a launchd plist for scheduled runs. These actions go beyond simple local image editing and carry privacy implications. They are generally coherent with the advertised features but are not limited to safe/local-only operations and are not fully declared in the registry metadata.

Install Mechanism

The registry lists no install spec, but SKILL.md suggests a one-liner 'uvx imagemine' and a permanent install via 'curl -LsSf uvx.sh/imagemine/install.sh | sh'. Piping a remote installer to sh is a high-risk pattern because it executes remote code without local review. The host uvx.sh is not documented in registry metadata; the install approach is therefore disproportionate and risky.

Credentials

The tool legitimately needs ANTHROPIC_API_KEY and GEMINI_API_KEY to call the services it claims to use. However, the skill stores keys in a local SQLite DB (~/.imagemine.db) by default (DB → env → prompt resolution order), which may store secrets in plaintext and increases exposure. The SKILL.md also accesses Photos face-detection metadata (PII) and will transmit images and derived prompts to external APIs — appropriate for the feature but privacy-sensitive and should be clearly declared in registry metadata.

Persistence & Privilege

The skill does not set always:true. It does, however, provide an option to install a launchd agent (writes ~/Library/LaunchAgents/imagemine.plist and instructs using launchctl) so it can run periodically and generate/upload images automatically. That behavior is coherent with the 'screensaver' feature but increases the blast radius (scheduled, autonomous uploads). Users should review generated plist contents and the scheduling choice before enabling.

What to consider before installing

Things to consider before installing/running this skill: - Registry metadata is incomplete: SKILL.md requires ANTHROPIC_API_KEY and GEMINI_API_KEY and uses a local DB and launchd, but the registry entry lists none — treat the package as only partially described. - Do not blindly run the recommended 'curl … | sh' installer. Inspect the install script (uvx.sh/imagemine/install.sh) before executing. Prefer manual installation or a checked package from a trusted source. - The tool sends your photos (and generated prompts) to external APIs (Anthropic and Google). If your photos contain sensitive people/data, that will be transmitted to third parties. - The skill saves API keys and run metadata to ~/.imagemine.db by default. Verify how the DB is protected (file permissions, whether secrets are encrypted) and consider using environment variables or a secure credential store instead of saving keys to disk. - The Photos integration reads face-detection names and can write back to Shared Albums and create a launchd job. Review and confirm all permissions, and inspect the generated launchd plist before loading it. - If you want to proceed: (1) inspect the GitHub repo referenced in the SKILL.md (https://github.com/hbmartin/imagemine) and the install script; (2) prefer using ephemeral or limited-scope API keys for testing; (3) avoid enabling scheduled launchd runs until you audit behavior; (4) consider running the tool on non-sensitive images first. If you want, I can: (a) fetch and summarize the installer script and repo README for additional checks (if you provide a URL you trust), or (b) show the likely launchd plist fields and what they mean so you can audit them before enabling scheduling.

Transform any photo into surrealist AI art via a two-step pipeline:

1. Claude writes a surrealist story + image prompt about your photo
2. Gemini generates a brand-new image from that description in a random visual style

Built by Harold Martin. Installable via uvx — no setup required beyond API keys.

Prerequisites

• Python 3.14+
• Anthropic API key (ANTHROPIC_API_KEY)
• Google Gemini API key (GEMINI_API_KEY)

Installation

One-off (no install)

uvx imagemine path/to/photo.jpg

Permanent install

curl -LsSf uvx.sh/imagemine/install.sh | sh

API Key Setup

Keys are resolved in order: SQLite DB → env vars → interactive prompt (saved to DB on first entry).

# Via environment
export ANTHROPIC_API_KEY=***
export GEMINI_API_KEY=***

# Or via interactive config wizard (saves to ~/.imagemine.db)
imagemine --config

Basic Usage

# Transform a single photo
imagemine photo.jpg

# Pick a random photo from a macOS Photos album
imagemine --input-album "Camera Roll"

# Save output to a specific directory
imagemine photo.jpg --output-dir ~/Desktop/output

# Use a specific visual style instead of random
imagemine photo.jpg --style "Ukiyo-e woodblock print, bold outlines, flat color"

# Tune creativity (default 1.0 for both)
imagemine photo.jpg --desc-temp 1.5 --img-temp 0.8

# Pick style interactively from a numbered table
imagemine photo.jpg --choose-style

# Blend multiple styles (enter comma-separated numbers)
imagemine photo.jpg --choose-style  # then enter: 1,5,12

# JSON output (for scripting)
imagemine photo.jpg --json

# Show recent run history with timing sparklines
imagemine --history

Visual Styles

35+ built-in styles including: Watercolor, 8-Bit Pixel Art, Ukiyo-e Woodblock, Neon Noir, Tarot Card, Vaporwave, Glitch Art, Renaissance Painting, and more.

imagemine --list-styles          # show all styles with usage count
imagemine --add-style            # add a custom style interactively
imagemine --remove-style         # remove styles interactively

Apple Photos Integration

imagemine reads face-detection names from Photos albums and uses them in prompts. Use character mappings to rename people before they reach the AI (e.g. "John" → "Captain America").

# Pick input from album, save generated image back to another album
imagemine --input-album "Camera Roll" --destination-album "AI Art"

# Manage character name mappings
imagemine --add-character-mapping
imagemine --list-character-mappings
imagemine --remove-character-mapping

Apple TV Screensaver (killer feature)

Run photo-alchemy on a schedule to continuously generate new art into a shared Photos album, then set that album as your Apple TV screensaver for a living, ever-changing art display.

Setup

1. Create two macOS Photos albums: one for source photos, one for output (make output a Shared Album so Apple TV can see it)
2. Configure albums:

imagemine --config
# Set INPUT_ALBUM and DESTINATION_ALBUM

3. Schedule via launchd (runs every N minutes):

imagemine --launchd 30
# Writes ~/Library/LaunchAgents/imagemine.plist and prints the launchctl command
launchctl load ~/Library/LaunchAgents/imagemine.plist

4. On Apple TV: Photos app → Shared Albums → select your output album → Set as Screen Saver

Apple TV Pitfalls

• Output album must be a Shared Album for Apple TV to see it
• New images appear in the screensaver automatically once added to the shared album
• Use --config-path if you want a non-default DB location with launchd

Configuration Reference

Key	Default	Description
ANTHROPIC_API_KEY	—	Claude API key
GEMINI_API_KEY	—	Gemini API key
CLAUDE_MODEL	claude-sonnet-4-6	Claude model for story/prompt generation
GEMINI_MODEL	gemini-3-pro-image-preview	Gemini model for image generation
DEFAULT_DESC_TEMP	1.0	Claude sampling temperature
DEFAULT_IMG_TEMP	1.0	Gemini sampling temperature
INPUT_ALBUM	—	macOS Photos album to pick input from
DESTINATION_ALBUM	—	macOS Photos album to save output to
ASPECT_RATIO	4:3	Output image aspect ratio (1:1, 3:4, 4:3, 9:16, 16:9)

Pipeline Steps (what happens under the hood)

1. Resize input to max 1024px (preserving aspect ratio), save to disk
2. Send resized image to Claude via Files API → generates surrealist story + image prompt
3. Pick a random visual style from the style library (or use --style)
4. Pass story + style + resized image to Gemini → generates the new image
5. Save run metadata to ~/.imagemine.db (SQLite)
6. Optionally import generated image into a macOS Photos album

Run History & Database

Every run is recorded in ~/.imagemine.db with input path, generated story, style used, model names, per-step timing (ms), and output path.

imagemine --history              # show recent runs with timing sparklines
imagemine --config-path ~/custom.db  # use a different DB location

Notes

• A new Claude description is generated on every run — no caching of stories
• --fresh picks from least-used styles (good for variety over time)
• --session-svg saves a styled SVG of the terminal session alongside the output image
• macOS only for Photos/launchd features; core image generation works on any platform