0marildo/imago

Imago is a Python command-line tool for organizing and understanding a photo library entirely on your own machine, with no cloud uploads or API keys. It combines several capabilities that typically require separate tools: finding duplicate or near-duplicate images, searching for photos by describing what is in them, reading and searching EXIF metadata, comparing two images pixel-by-pixel, and moving unwanted files to a safe trash you can restore from. The semantic search feature uses a model called CLIP to match text descriptions against image content. You type something like "a photo of a strawberry" and it returns images that contain that thing, regardless of their filenames. Similarly, you can use a reference image to find visually similar images using perceptual hashing, a technique that produces a compact fingerprint for each photo and compares them. The find-similar command groups near-duplicate images in a folder together, using a configurable threshold so you can tune how strict the matching is. The diff command shows a pixel-level heatmap of the differences between two images along with a numerical similarity score. The safe trash feature moves files to a separate trash directory rather than permanently deleting them. You can list what is in trash, restore individual files, or empty it when you are sure. This is useful when cleaning up duplicates found by find-similar. The architecture is designed to be extended. Each capability is a self-contained module that registers itself automatically with the runtime. Adding a new feature means writing one Python file with no changes to the CLI or configuration. The roadmap lists planned additions including OCR, face detection, object detection, AI captioning, and a web interface. Imago is installed via pip and requires Python 3.11 or newer. The project is licensed under MIT.