AI photo search and Lightroom Classic editing with Codex

What is available in the Photos preview?

Metachlorian now includes photo indexing, visual search, people, collections and an editing workflow for Lightroom Classic in its current source preview. These features are not included in the published v0.2.0 desktop installers. Start with the source setup instructions.

Codex, or another vision-capable agent connected through the Model Context Protocol (MCP), makes the photographic decisions. A small bundled Lightroom plug-in connects Metachlorian to the catalogue and Adobe’s renderer. It does not replace your agent or require a second AI subscription.

Global edits are enabled for Lightroom Classic 14.2–15.6, with controls checked per photograph. AI subject, sky and background masks require 15.6. Automated tests cover the service, connector contracts and recovery behaviour; live Lightroom certification on macOS and Windows and real-photo preference evaluation remain pending. Try an expendable catalogue first. This is a Classic integration, not an integration with the cloud Lightroom application.

Index a catalogue without copying your originals

Run Metachlorian on the same computer and OS account as Lightroom Classic. Open Photos → Enable Photos and follow Choose your photos → Connect Lightroom → Use your agent. Select Copy connector files, then add the displayed MetachlorianPhotos.lrplugin directory through Lightroom’s File → Plug-in Manager → Add. If updating an existing plug-in, copy the new files and select Reload Plug-in in Lightroom. Select Check connection in Metachlorian: a real response shows the Lightroom version, catalogue and connector version. Copied files alone do not prove a connection. Then choose Sync catalogue to index metadata and analyse available renditions.

The connector uses Lightroom to access existing previews, including Smart Previews when available. It does not write directly to .lrcat files or create Smart Previews for the entire catalogue. An offline original can still have a searchable record; the evidence available depends on the previews Lightroom can supply.

You can also index a folder in place. JPEG, PNG, TIFF and WebP are supported through Pillow; the photo installation includes RAW and HEIC decoders. When a folder-indexed file already exists in the open Lightroom catalogue, preview and context requests match it to its existing master. RAW previews can then come from Lightroom even without a local RAW decoder. Only selected files outside that catalogue are imported in place when editing begins. A NAS or Docker container can host video search, but cannot control a desktop Lightroom installation through this local connector.

How do I know the Lightroom plug-in is working?

Keep Lightroom and Metachlorian open under the same OS account. In Photos, select Check connection. A verified response identifies the open catalogue and version and explains whether editing is available for this account. In Lightroom’s Plug-in Manager, the Metachlorian Photos panel shows the last authenticated request and action; select Refresh status to update it.

If the connector is waiting, select Start connection. If Metachlorian asks for an update, copy the current files and reload the plug-in. Both applications must use the same local ports: the defaults are 58773 and 58774. Use Activity → Refresh analysis to retry photos that lacked previews before connection setup. Resume an interrupted edit job after reconnecting.

Choose the best images for your brief

Start with what you want to remember or communicate. For family photographs, expression, gesture and relationships often matter as much as technical perfection. A laugh with closed eyes can be the right frame. For travel, balance people, places, details and wider context. For portraits, consider the eyes, pose, background, light and believable skin colour together.

Search combines visual content with filters for named people, dates, folders, catalogues, ratings, camera and lens. Burst grouping helps you compare related frames and avoid filling a shortlist with nearly identical moments. Names are human-confirmed; small faces, children and unusual poses need checking.

The agent receives actual previews, optional detail crops and qualified measurements of clipping, sharpness, face regions and framing. Aperture, shutter speed and ISO explain capture conditions. They are not rules for deciding whether a photograph is good. A Smart Preview cannot establish original-resolution eye focus or RAW highlight recoverability, and a generic aesthetic score cannot decide which photograph of your family matters most.

Try this brief: “Find 20 favourites from our July holiday featuring my son. Compare similar frames, include quiet moments as well as smiles, and keep some environmental photographs. Edit naturally in Lightroom on virtual copies. Inspect the renders and put the results in ‘July family favourites’.”

Connect Codex through the existing MCP server

Create a token in Settings → API tokens for agents with library:read, photos:edit and collections:write. Search and inspection work with read-only access; editing requires its separate scope. Set METACHLORIAN_TOKEN in the environment used to launch Codex, and add the following to your Codex configuration:

[mcp_servers.metachlorian]
url = "http://127.0.0.1:8765/mcp/"
bearer_token_env_var = "METACHLORIAN_TOKEN"

Use the server URL displayed in Photos if your desktop build uses a different port. Connect to the running server over HTTP so it owns the Lightroom connection and durable job queue. The same MCP server also supports video search and editing handoffs.

1. get_photo_workflow_status verifies the connector, active catalogue, editing permissions and decoder availability. The agent should explain any blocker before proceeding.
2. search_photos finds candidates; get_photo_previews supplies actual images for comparison.
3. get_photo_edit_context reports the current Lightroom revision, available controls and recovery snapshots.
4. begin_photo_edits creates owned virtual copies and fresh baselines.
5. apply_photo_edit applies supported adjustments and produces a new Lightroom render. The agent inspects it before another refinement.
6. finish_photo_edits saves visually reviewed copies to a named collection after checking their revisions.

The Photos Activity view separates virtual copies ready for an agent from edits ready for review. Preparing copies does not apply a look by itself. Ask the agent to report the selected file, virtual copy, actual adjustments, rendered review and any unverified detail. If it uses Lightroom manually instead of the MCP, it should say so.

Interrupted jobs can be inspected and resumed. Reuse the same idempotency key when retrying an uncertain request; a conflict requires fresh context and review. See the complete tool contract and recovery instructions.

Improve the photograph with supported Lightroom controls

Begin with the image’s intent, then make a small set of deliberate adjustments. Check composition and distracting edges; balance exposure and white balance; shape contrast and colour; inspect skin and highlight transitions; then evaluate detail at an appropriate scale. Compare each candidate with its baseline. This workflow allows up to three refinement rounds per edit session.

The connector validates controls available on each photograph, including their units and ranges. Supported families include exposure and tone, white balance, RGB and parametric curves, HSL, colour grading, crop and straightening, perspective, lens controls, sharpening, noise reduction, vignette and grain, plus simple subject, sky and background masks on Classic 15.6. RAW temperature is expressed in Kelvin; JPEG temperature uses relative adjustments.

Edits target owned virtual copies. Fresh Lightroom renders let the agent inspect Adobe’s actual output, while snapshots and revision checks support recovery and detect intervening human changes. A settings readback alone does not demonstrate a pleasing result.

Manual or capability-gated operations: Point Color, complex mask geometry, guided perspective, healing and Generative Remove, reflection removal, Lens Blur, Enhance/AI Denoise, HDR and panorama merges, and HDR output. The workflow explains when a Lightroom handoff is needed rather than reporting an unsupported operation as completed.

How much storage does photo indexing use?

Originals stay where they are. The default 256 MiB cache covers retained JPEG previews and reserved temporary Lightroom renders together. Older previews are evicted; face crops are created on request. The photo model pack downloads approximately 947 MB once and reuses models already installed for video analysis.

A recorded synthetic benchmark used about 650 MiB for 100,000 photo records, including its reusable vector index and three face observations per image. That excludes model weights, preview storage and Lightroom-owned files. It measures index storage and retrieval, not photographic quality, and real catalogues will vary. Read the benchmark methodology and results.

Virtual copies, snapshots and Adobe AI data can grow Lightroom’s catalogue and associated files. Metachlorian’s cache budget does not govern Adobe’s storage. The approach avoids duplicating your originals, but it does need disk space for its own index.

Local analysis and your chosen agent

Photo analysis runs locally and does not enter the public video community index. Previews explicitly requested through MCP are sent to your chosen agent, which may run on a hosted service. Choose that agent with your family photographs and privacy preferences in mind.

Face embeddings are not exposed through the photo API. People are named and regrouped by human accounts, while agents have scoped access to search, inspection and editing. The catalogue remains authoritative for Lightroom settings.

Learn the tools and evaluate the results

Adobe’s Lightroom Classic tutorials and Julieanne Kost’s Lightroom training cover composition, profiles, tone, colour, masks, detail and output. Use them to develop a visual goal and understand the tradeoffs behind each control.

The project’s research notes explain the open-source tooling and learning resources. The photo documentation records the supported control families, storage model and outstanding platform checks.

Evaluate edits against untouched baselines using portraits, travel and family photographs you know. Personal preference and visible regressions matter more than a headline score. Automated tests are useful evidence about software behaviour; they do not prove that an edit looks better.