Immich Pet

Manage your self-hosted Immich photo library with AI-powered tools for uploading assets, creating albums, searching photos, and managing metadata.

Features

• 235 OpenAPI-generated tools covering the full Immich API
• Core tools (45): Albums, Assets, and Search functionality loaded by default
• Optional tool groups (190): Enable additional features as needed via environment variables
• Read-only mode support for safe exploration
• Self-hosted compatible with any Immich instance

Quick Start

1. Get Your Immich API Key

1. Log into your Immich web interface
2. Go to Settings > Account > API Keys
3. Click New API Key and give it a name
4. Copy the generated key

2. Configure Environment Variables

Copy .env.example to .env and fill in your values:

IMMICH_API_KEY=your_api_key_here
IMMICH_BASE_URL=https://immich.example.com

3. Test Connection

opencode run "test immich connection"

Core Tools (Always Available)

The following 45 tools are always loaded:

Albums (12 tools)

• immich-get-all-albums - List all albums
• immich-create-album - Create a new album
• immich-get-album-info - Get album details
• immich-update-album-info - Update album information
• immich-delete-album - Delete an album
• immich-add-assets-to-album - Add photos/videos to album
• immich-remove-asset-from-album - Remove assets from album
• And 5 more album management tools...

Assets (23 tools)

• immich-upload-asset - Upload a photo or video
• immich-get-asset-info - Get asset details
• immich-update-asset - Update asset information
• immich-delete-assets - Delete one or more assets
• immich-get-asset-statistics - Get photo library statistics
• immich-download-asset - Download original asset
• immich-view-asset - Get asset thumbnail
• And 16 more asset management tools...

Search (10 tools)

• immich-search-smart - Smart search using AI
• immich-search-metadata - Search by metadata (date, location, camera, etc.)
• immich-search-places - Search photos by location
• immich-search-person - Search for specific people
• immich-get-explore-data - Get explore page data
• And 5 more search tools...

Optional Tool Groups

Enable additional functionality by setting environment variables:

Most Useful Optional Groups

# Enable people/face recognition tools (11 tools)
IMMICH_LOAD_PEOPLE_TOOLS=true

# Enable shared link management (8 tools)
IMMICH_LOAD_SHARED_LINKS_TOOLS=true

# Enable tag management (9 tools)
IMMICH_LOAD_TAGS_TOOLS=true

# Enable library management (8 tools)
IMMICH_LOAD_LIBRARIES_TOOLS=true

# Enable timeline/bucket tools (2 tools)
IMMICH_LOAD_TIMELINE_TOOLS=true

# Enable trash/restore functionality (3 tools)
IMMICH_LOAD_TRASH_TOOLS=true

All Available Optional Groups

See .env.example for the complete list of 25+ optional tool groups including:

• Activities, Memories, Faces, Duplicates
• Map/location tools, Server info, Workflows
• Admin tools (user management, backups, etc.)

Example Queries

# Basic operations
opencode run "test immich connection"
opencode run "get statistics about my photo library"
opencode run "list all my albums"

# Search
opencode run "search for photos of mountains"
opencode run "find photos taken in Paris"
opencode run "search for photos from last summer"

# Album management
opencode run "create a new album called Vacation 2024"
opencode run "add photos to my Vacation album"

# Asset management
opencode run "get details about asset abc123"
opencode run "update the description for photo xyz789"

Read-Only Mode

Enable read-only mode to prevent accidental modifications:

# Enable read-only for immich
pets read-only immich on

# Or set environment variable
IMMICH_READ_ONLY=true

In read-only mode, only GET/HEAD/OPTIONS operations are available (107 tools). All write operations (128 tools) are disabled.

Configuration

Required Environment Variables

| Variable | Description | |----------|-------------| | IMMICH_API_KEY | API key from Immich (Settings > Account > API Keys) | | IMMICH_BASE_URL | Full URL to your Immich server (e.g., https://immich.example.com) |

Optional Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | IMMICH_READ_ONLY | Enable read-only mode | false | | IMMICH_LOAD_*_TOOLS | Enable specific tool groups | false |

OpenAPI Generation

This pet uses OpenAPI generation from the official Immich specification. To regenerate tools after an Immich API update:

cd pets/immich
pets generate-openapi --verbose

The generator will:

1. Fetch the latest OpenAPI spec from the Immich GitHub repo
2. Generate 235 tools from 161 API endpoints
3. Create openapi-client.ts with all tool definitions
4. Configure core endpoints and optional tool groups

Troubleshooting

"IMMICH_BASE_URL environment variable is required"

Make sure you've set IMMICH_BASE_URL in your .env file with the full URL to your Immich server.

Connection fails with 401 Unauthorized

1. Verify your API key is correct
2. Check that the API key hasn't been revoked in Immich settings
3. Ensure the API key has the necessary permissions

"Failed to connect" errors

1. Verify your Immich server is accessible at the IMMICH_BASE_URL
2. Check if you need to include the port number (e.g., http://192.168.1.100:2283)
3. Ensure your Immich server is running and healthy

Can't find a specific tool

1. Check if the tool is in an optional group - see .env.example
2. Enable the relevant tool group with IMMICH_LOAD_*_TOOLS=true
3. Run opencode run "list immich tools" to see all available tools

API Version

This pet is generated from Immich API v2.5.0 (OpenAPI 3.0.0 specification).

Links

• Immich Homepage
• Immich Documentation
• Immich GitHub
• Immich API Docs
• OpenAPI Spec

License

This pet is part of the OpenPets project. See the main repository for license information.