Immich Cat

A keyboard-driven image categorization tool built with Elm that integrates with Immich. Efficiently categorize and manage large photo collections with vim-style navigation.

Features

• Keyboard-driven interface - Vim-style navigation and shortcuts
• Real-time viewing - Authenticated image/video loading from Immich
• Smart album management - Categorize assets with automatic count tracking
• Intelligent keybindings - Conflict-free album shortcuts with fuzzy matching
• Advanced search - Fuzzy search and filtering capabilities
• Batch operations - Bulk favorites, archiving, and album management
• Asset preloading - Intelligent caching for smooth navigation

Demo

See Immich Cat in action - this 1-minute demo shows the core workflow of efficiently categorizing photos with single-keypress album assignment:

demo.mp4

What you'll see in the demo:

• Loading albums from Immich and navigating through photos with vim-style keys
• Album keybindings displayed on screen (like a for "Animals", f for "Family")
• Single-keypress photo categorization - just press a letter to add the current photo to that album
• Search mode for finding albums not shown on screen
• The speed difference: traditional web interfaces require multiple clicks per photo, here it's one keypress per album

Quick Start

docker run -p 8000:8000 \
  -e IMMICH_URL=https://your-immich-server.com \
  -e IMMICH_API_KEY=your_api_key \
  ghcr.io/ohare93/immich-cat:latest

Open http://localhost:8000 in your browser.

Get your API key from Immich web interface → Account Settings → API Keys.

API Key Permissions

Immich Cat requires these minimum permissions (Immich v1.138.0+):

Permission	Enables
album.read	View albums, check asset membership
album.create	Create new albums
albumAsset.create	Add assets to albums
albumAsset.delete	Remove assets from albums
asset.read	Browse and search assets
asset.update	Favorite and archive assets

Note: Older Immich versions may require the all permission instead.

See DEPLOYMENT.md for:

• Docker Compose setup
• Nix/NixOS installation
• Development setup
• CORS configuration for Traefik (required for reverse proxy setups)
• Troubleshooting guide

How it Works

The app connects to your existing Immich server and loads all your albums and assets. You don't need to recreate anything - it works with your current photo organization.

The key advantage: In Immich's web interface, adding a photo to an album requires multiple clicks (select photo → add to album → search/select album → confirm). Here, it's just one keypress per album thanks to automatically generated keybindings.

💡 See it in action: Watch the demo above to see exactly how this works!

Usage

Getting Started

1. After starting the app, it will load your Immich albums and assets
2. Use vim-style navigation to browse through your photos
3. See your top albums with their auto-generated keybindings displayed on screen (like a for "Animals", v for "Vacation 2024")
4. Navigate to any photo and press the album's key to instantly add it (e.g., press a to add current photo to "Animals")
5. Press ? anytime to see all available shortcuts

📺 New to the workflow? Check out the demo video for a visual walkthrough!

Quick Album Assignment (Main Feature)

The app automatically generates single-key shortcuts for your most-used albums and displays them on screen at all times:

• a might be "Animals"
• v might be "Vacation 2024"
• f might be "Family"
• And so on...

Simply navigate to any photo and press the letter - that's it! No menus, no clicking, no searching. The keybindings are always visible.

Interface Modes

• Normal Mode (default): Navigate and manage assets with keyboard shortcuts (top album keybindings always visible)
• Insert Mode: Search for albums not shown on screen, or create new albums
• Scroll View Mode: For viewing large images that need scrolling

Key Bindings

Navigation

• ←/→ (Arrow Keys) - Previous/next asset
• Backspace - Previous asset
• Space/Enter - Next asset
• Home/End - Jump to first/last asset (Grid view only)
• Esc - Return to normal mode/main menu

Asset Actions

• F - Toggle favorite status
• D - Toggle archive/delete
• Y - Copy image to clipboard
• K - Open current asset in Immich web interface
• L - Load/toggle video (for long videos)

Album Management

• a-z (displayed on screen) - Instantly add current photo to specific album
• I - Search for albums not visible on screen, or create new albums
• R - Reload albums from server

View Controls

• G - Switch to grid view
• S - Toggle scroll view (for viewing large images)
• T - Toggle time view (Absolute/Relative)
• ? - Show help with all current keybindings

Scroll View Mode (Large Images)

• h/j/k/l - Scroll left/down/up/right (vim-style)
• PageUp/PageDown - Scroll full page up/down
• Ctrl+u/d - Scroll half page up/down
• Ctrl+f/b - Scroll full page up/down

Album/Search Navigation

• PageUp/PageDown - Page through album/search results
• Ctrl+u/d - Half page up/down through results
• Ctrl+f/b - Full page forward/back through results

Note: Ctrl+u/d/f/b keys work differently depending on mode: for scrolling images in Scroll View Mode, or for navigating through album/search results in other contexts.

Example: With "Animals" = a visible on screen, just press a while viewing any photo to add it to Animals album. Use I only if you need an album that's not displayed.

License

MIT License - see LICENSE file for details.