Aegis Photo Commander Documentation

Aegis Photo Commander is a darkroom workbench for individual photos. You load a small set of photos, work on one at a time with precision tools or with an AI assistant, step backwards and forwards through your edits freely, and write out a finished file when you are happy.

It is a companion to Aegis Photo Voyager, which manages your full library. Voyager finds the photo; Commander perfects it. Neither requires the other.

What Needs Setting Up

The editing tools work on their own with no configuration at all. Two groups of features depend on outside software:

• The AI Assistant and the three vision Analysis tools need a local LLM server — Ollama or LM Studio — running with a vision-capable model. See Configuration.
• The AI Generate tools need an NVIDIA GPU and a one-time model download. See Generative AI.

Download the Beta Product Overview

The Four Panels

The main window is split into panels you can show or hide from the View menu. Drag the dividers between them to resize; your layout is remembered the next time you start the app.

• Working Set (left) — thumbnails of the photos loaded into this session. Click one to make it the active photo.
• Live View (centre) — the active photo, with zoom controls, a before/after toggle and a status line.
• Workbench Tools (right) — the tool list, the settings for whichever tool you are using, Undo/Redo, History, and the Commit button.
• AI Assistant — the chat panel. It is hidden until you switch it on in the View menu.

Your First Edit

1. Add photos. Click ＋ Add Photos in the Working Set, or start the app with filenames on the command line. JPEG, PNG, HEIC/HEIF, WebP, AVIF, TIFF and BMP are all supported. Camera raw files are not.
2. Pick one. Click its thumbnail. It appears in the Live View and the Workbench tools become available.
3. Choose a tool. Open a palette in the Workbench, or type in the search box at the top of the panel. The tool's settings replace the tool list; press ← TOOLS to go back.
4. Adjust and apply. Most tools preview live in the Live View as you move the sliders. Apply commits the step to your history; Cancel throws it away.
5. Commit. When the photo is finished, press COMMIT SESSION and choose where to save it.

Undo, Redo & History

Undo and Redo sit at the bottom of the Workbench panel. The History section at the bottom of the tool list shows every step you have applied, and you can click any entry to jump straight back to that point — including all the way back to the untouched original.

History is kept per photo. Switching to another thumbnail and back brings your undo stack with you, so you can work on several photos in one session without losing your place.

Edits made by the AI Assistant are recorded identically. There is no separate agent history and nothing special about undoing the assistant's work.

Committing vs. Exporting

• COMMIT SESSION finishes the photo: it copies the current state to the file you choose, deletes the intermediate working files, and clears the history. Use it when you are done.
• Save As (in Files and Formats) writes a copy in a format you pick and leaves your session and history intact. Use it to produce a JPEG for sharing while you carry on editing. It can also convert every photo in the Working Set in one go.

The Working Set

The Working Set is the short list of photos loaded into the current session — not your whole library. It is deliberately small: these are the photos you are working on right now.

• ＋ Add Photos opens a file picker; you can select several files at once.
• Click a thumbnail to make that photo active. The active photo is outlined and is what every tool and the AI Assistant operate on.
• Hover a thumbnail and click the × in its corner to drop that photo from the session. This only removes it from the session; the file on disk is untouched.
• Clear All empties the set. The footer shows how many photos are loaded.

The Working Set is saved when you quit and restored when you start again, so an interrupted session picks up where it left off.

Loading Photos From Outside the App

# Load these files at startup
aegisphotocommander photo1.jpg photo2.heic

# Load every path listed in a JSON array
aegisphotocommander --input-json paths.json

# Verbose logging, for tracking down a problem
aegisphotocommander --debug

Only one copy of the app runs at a time. If it is already open, launching it again with filenames adds those photos to the existing Working Set instead of opening a second window.

Library Search

Library Search (under Files and Formats) queries your Aegis Photo Voyager library and adds the matches straight into the Working Set. You can search by scene description, by a person's name, by date range, or by any combination, and cap the number of results.

It needs a Voyager library on this machine; without one the search returns nothing. Photos that were deleted or hidden in Voyager are deliberately excluded from results. Library Search is also the one tool that runs without an active photo.

The Live View

The centre panel always shows the current state of the active photo, including a live preview while you are dragging a tool's sliders.

Zooming and Panning

• The four buttons above the image are Zoom In, Zoom Out, Fit to Screen and Actual Size (1:1).
• Scroll the mouse wheel to zoom towards the pointer.
• Double-click the image to fit it back to the window.
• Drag to pan when the photo is larger than the panel.

Use Actual Size whenever you judge sharpening or noise reduction — a fitted view hides both.

Before / After

The Before/After button, or the \ key, flips between your edited result and the untouched original. It switches itself off as soon as a new edit lands, so you always see the effect of what just happened.

The Status Line

Underneath the image you get the filename, the pixel dimensions of what is currently displayed, and how many edits deep you are — Original, or 3 edits. If the dimensions change after a crop or resize, this is where you confirm it.

Markers and Overlays

Analysis tools and the AI Assistant can draw on top of the photo: composition grids, boxes around a subject or a detected face, leading lines, and crop previews. These are overlays only — they are never burned into the image. Clear Markers removes all of them.

Picking and Painting on the Image

Some tools take their input directly from the Live View rather than from sliders:

• White Balance and the HSL Tuner let you click a colour in the photo to target it. The HSL Tuner can also be dragged up and down over a colour to adjust it in place.
• Magic Eraser, Privacy Blur, AI Inpaint and AI Text Edit let you paint a mask over the area to work on. The cursor becomes a circle the size of your brush.
• Crop & Level and Smart Crop draw a draggable crop rectangle over the image.

How a Tool Works

Tools live in the Workbench panel on the right, grouped into palettes: Darkroom, Workshop, AI Generate, Lens Kit, Files and Formats and Analysis, with History at the bottom. Every palette heading stays on screen whether or not it is open, and the number beside each one tells you how many tools it holds.

Click a heading to open that palette; the one you open is marked in teal and whichever was open closes. Click the open heading again to collapse it and see the full list of palettes at once. If you already know the tool you want, press Ctrl+F and type — searching looks across every palette at once. Everything is also in the Tools menu in the header bar.

Select a photo first, then a tool. The tool's settings take over the Workbench panel and most tools preview straight into the Live View as you move the sliders. Apply commits the step to your history; Cancel or ← TOOLS throws it away. A slow tool runs in the background so the window stays responsive.

Darkroom

The classic tonal and colour adjustments.

Workshop

Repair and retouching, including the tools that clean up a photo for sharing.

• Magic Eraser — paint over an unwanted object or a photobomber and it is filled in from the surrounding image. Set the brush size first; Clear Selection starts the mask over. For a demanding fill, AI Inpaint gives a better result.
• Privacy Blur — obscure faces, text or number plates before you share a photo. Choose blur, pixelate or blackout, then mark the areas with a brush, a rectangle or an ellipse. The Faces, Text and Plates buttons ask the vision model to find those targets for you and mark them automatically. Strength sets the intensity and feathering softens the edges.
• Neural De-noise — separate luminance and colour noise reduction, for photos shot at high ISO. Luminance smooths the grain, colour removes the blotchy patches. Check the result at Actual Size.
• Sky Replace — swap a flat sky for blue, sunset, stormy or starry. Find Line detects the horizon for you and you can drag the points to fix where it gets the edge wrong. Brightness, warmth and feathering blend the new sky into the scene.

Lens Kit

Geometry: framing, straightening and lens correction.

• Rotate — rotate left or right in fixed steps with high-quality resampling.
• Flip — mirror horizontally or vertically.
• Crop & Level — drag a crop rectangle on the image or type exact pixel coordinates. Aspect presets cover free, original, 1:1, 16:9, 4:5, 3:2, 2:3 and 4:3.
• Smart Crop — the vision model studies the composition and proposes several crops with its reasoning. Preview each one on the image and take the one you like, or none of them.
• Perspective Fix — keystone correction for converging verticals, the usual problem when photographing a tall building. Correct vertical and horizontal tilt, then zoom to fill the frame again.
• Lens Profile — correct barrel and pincushion distortion, vignetting, and red/cyan and blue/yellow colour fringing. Auto crop trims the curved edges that correction leaves behind.

Files and Formats

• Save As — export a copy as JPEG, JPEG XL, PNG, WebP, HEIC, HEIF, AVIF or TIFF. Switch on batch to convert every photo in the Working Set at once, with an optional filename prefix or suffix. Your session and history stay as they are.
• Library Search — pull photos out of your Aegis Photo Voyager library and into the Working Set. See Library Search.
• Info — file properties and metadata at a glance.
• Watermark — a text watermark in any of nine positions, with font size, opacity and colour.
• Metadata Editor — set the title, artist, copyright, comment and star rating stored in the file.

Analysis

These four tools read the photo and report back. None of them change a pixel, so they never appear in your history. The first three ask a vision model to look at the image and need Ollama or LM Studio running.

• Describe — a written description of the subject, lighting, mood and atmosphere.
• Quality — a technical and aesthetic assessment: sharpness, exposure, noise, and what is working or not.
• Composition — framing, subject placement and compositional rules, drawn onto the Live View as grids, subject boxes and leading lines.
• Meta Data — no AI needed. File properties, EXIF camera and exposure data, GPS location, and the photo's Aegis Photo Voyager record if it has one.

The AI Assistant

The AI Assistant is a chat panel that can drive the application for you. Ask it in ordinary language to adjust a photo, to tell you what it sees, or to find something in your library, and it carries out the work using the same tools you would have clicked.

The panel is hidden when you first start. Switch it on under View → AI Assistant. It needs a local LLM server running — see Configuration.

Agent Edits Are Ordinary Edits

Anything the assistant does goes through exactly the same machinery as a button click. It lands in your History, the Undo button reverses it, and the Live View updates immediately. You can undo the agent's work yourself, or ask it to: "undo that". There is no separate agent mode to get stuck in.

What to Ask It

Adjust the photo. "Make this warmer." "Rotate it 90 degrees and crop it square." "Lift the shadows a little without blowing the highlights." "Add a watermark saying © 2026 in the bottom right." It maps everyday language onto the real controls — "make it pop" becomes contrast, exposure and blacks.

Look at the photo. "What's in this photo?" "Is this sharp enough to print?" "Show me where the faces are" — it can draw boxes and lines over the Live View to point things out.

Work across the Working Set. "What photos do I have loaded?" "Switch to the beach one." "Apply that same exposure to all of them." "Find photos of Elena from last summer" searches your Voyager library and loads the matches.

Privacy and generative work. "Blur every face in this photo" — it locates them first, then applies the redaction. "Put a sports car in the driveway" is generative, so it needs the FLUX.2 setup.

Working With It Well

• Say which photo. It acts on the active photo. If you mean a different one, select it first or tell the assistant to switch.
• Check its analysis is fresh. When you change photos it is told to re-examine rather than reuse what it said before, but if a description looks like it belongs to the previous image, ask again explicitly.
• Verify automatic detection. When it finds faces or text for redaction, look at the marked regions before you accept the result.
• Watch the status bar. The header shows 🤖 Thinking… while it works, and replies stream in as they are generated.
• Small steps beat one big instruction. Several short requests are easier to judge and undo than one long one.

The Three Processing Modes

Every reply starts by declaring which route the assistant took:

• Specialized Aegis Tools — the precise, predictable pixel adjustments. This is the right mode for edits.
• Generative AI (FLUX.2) — synthesising new content. Needs a CUDA GPU.
• Direct Vision Pass-through — the vision model looking at the image and answering in words. This is the right mode for questions and opinions.

Usually it chooses sensibly. When it does not, force the choice with a prefix:

So "AI Vision: is the horizon level?" gets you an opinion, while "Technical Edit: level the horizon" gets you a rotation.

Voice Input

Press the 🎙️ button to dictate instead of typing. It records for eight seconds, transcribes, and drops the text into the input box for you to check and send. The ⚙️ button reveals two options: Auto-Send Transcriptions sends immediately without the check, and Recording Audio Feedback plays a cue when recording starts.

Generative AI

The four tools in the AI Generate category do something the other tools cannot: they invent new pixels. Where Magic Eraser patches a hole with material borrowed from nearby, AI Inpaint generates plausible new content from a description you write. The model behind them is FLUX.2 Klein, running locally on your graphics card.

What You Need

• An NVIDIA GPU with CUDA. There is no CPU fallback — without a supported card these four tools stay unavailable, and the rest of the application is unaffected.
• Video memory. The 4B model needs about 6 GB at minimum and runs comfortably with 10 GB. The 9B model needs about 10 GB at minimum and 16 GB to be comfortable.
• Disk space and a first download. Model weights are several gigabytes, fetched once then cached.
• A Hugging Face token for the 9B model, which is gated. The 4B model is not.

One-Time Setup

1. Check the GPU status line at the top of Configure → Generative AI. It tells you whether a CUDA card was found and how much memory it has.
2. Choose a model variant. FLUX.2-klein-4B is faster, lighter and Apache 2.0 licensed — start here. FLUX.2-klein-9B gives higher quality but is larger and carries a non-commercial licence.
3. For the 9B model, create a read token on Hugging Face, accept the model licence on its page, then paste the token into Hugging Face Authentication on the Flux Model tab.
4. Press Load Model weights, or run Test Engine & GPU to check the whole setup at once. The first run downloads the model, which takes a while.

Performance Settings

• Precision — auto picks for you. bf16 is the best quality and needs the most memory; fp8 cuts memory use noticeably for a small quality cost. Drop to fp8 if generation fails for lack of memory.
• CPU Offload — keeps parts of the model in system RAM instead of on the card. Slower, but it is what makes a card under 16 GB workable.
• Default inference steps — between 1 and 8, default 4. More steps means more detail and more waiting.
• Auto-unload — frees the video memory after a number of idle minutes. Set it to Never to keep the model resident.
• Model cache directory — where the weights are kept. Point it at another drive if your home partition is tight.

The Four Tools

• AI Inpaint — paint a mask over the target area, then write what should be there: "replace the red jacket with a dark navy leather one". Strength controls how completely the masked pixels are overwritten. Give it a seed to reproduce a result exactly.
• AI Composite — add two or more reference photos, then describe how they should combine, referring to the images by number: "place the person from image 1 on the beach in image 2".
• AI Style Match — borrow the colour grading, grain, contrast and lighting of one photo for another, while your composition and structure stay put.
• AI Text Edit — mask a text region and give the new wording, with the target text in quotes. A font style hint — serif, sans-serif, handwritten, carved, neon, gothic or modern — steers the lettering towards what is already there.

Getting Good Results

• Mask generously but not wildly. Include a little of the surrounding area so the model can blend the edges, but do not mask half the photo when you mean one object.
• Describe the result, not the operation. "A wooden bench under the tree" works better than "remove the bin and put something there".
• Expect to iterate. Generation is not deterministic unless you fix the seed.
• Undo works normally. A generated result is an ordinary step in your history.

Configuration

Open Configure in the header bar. Settings are saved as you change them — there is no separate save button — and are remembered between sessions.

AI Engine

This is where you connect the application to a local language model. The AI Assistant and the Describe, Quality, Composition and Smart Crop tools all depend on it; nothing else does.

• Framework — Ollama or LM Studio. Each keeps its own URL and model, so you can switch between them without re-entering anything.
• Base URL — where that server is listening. The defaults are http://localhost:11434 for Ollama and http://localhost:1234/v1 for LM Studio.
• Active Model — press the fetch button to list what is installed on the server and pick from it, or type a name by hand.

AI Tuning

• Analysis Image Size — how large an image is sent to the model: original size, 2048, 1024, 512 or 256 pixels. This is the main speed-versus-accuracy dial. Small images come back quickly but hide fine detail, which matters for questions about sharpness, small faces or text.
• Context Window — how much conversation the model can hold at once, in tokens. A larger window lets a long session stay coherent but uses more memory. Keep it within what your model and hardware support.

LLM Prompts

The prompt template used for structured image analysis — the one that asks the model to return tags, descriptions, objects, people, places, mood, quality, actions and category as JSON. Edit it if you want different fields or different vocabulary, and press Restore Default to put it back. The template is stored separately from the assistant's own instructions, so a bad edit cannot break the AI Assistant.

Storage

Where edited photos are written when a tool saves a result: either the same directory as the source photo, or one folder you choose (the default is ~/Pictures/AegisPhotoCommander/). This setting does not affect COMMIT SESSION or Save As, where you pick the destination yourself each time.

Keyboard & Mouse

Keyboard

Mouse in the Live View

Mouse in the Working Set

Where Files Live

• ~/.aegisphotocommander/ — application data.
• ~/.aegisphotocommander/tmp/ — working copies of photos mid-edit, plus the log files. Committing a photo clears out its intermediate files. If a session ends badly, this folder is safe to empty when the application is closed.
• ~/Pictures/AegisPhotoCommander/ — the default output folder, if you choose the single-directory storage mode.
• Window layout, panel visibility and all your settings are stored by the system's own settings mechanism, under the name Aegis / PhotoCommander.

Troubleshooting

A panel has disappeared

Open the View menu and switch it back on. The AI Assistant is hidden by default. If the layout is badly wrong, drag the dividers between the panels to redistribute the space.

"Please select a photo first"

Almost every tool works on the active photo. Add photos to the Working Set and click one so it is highlighted. Library Search is the only tool that runs without an active photo.

The AI Assistant or an Analysis tool fails

1. Is the server running? Start Ollama or LM Studio and confirm it responds on its own.
2. Does the URL match? Check Configure → AI Engine against where your server is actually listening.
3. Is the model installed? Use the fetch button on the AI Engine tab. If the list is empty, the application cannot reach the server; if your model is missing from it, install it first.
4. Can the model see? Describe, Quality, Composition and Smart Crop send an image. A text-only model will refuse or invent an answer.

The error message in the panel names the provider, URL and model it tried, which usually identifies which of the four is wrong.

Analysis is slow, or the answers are vague

Both are governed by Analysis Image Size in Configure → AI Tuning. Lower it for speed; raise it when you are asking about detail the model clearly cannot make out. A large context window also slows things down and uses more memory.

The AI Generate tools are unavailable

• No CUDA GPU found. These four tools require an NVIDIA card; there is no CPU fallback. The GPU status line in Configure → Generative AI reports what was detected.
• Not enough video memory. Switch Precision to fp8, turn on CPU Offload, and use the 4B model rather than the 9B.
• Access denied when downloading. The 9B model is gated: create a read token on Hugging Face, accept the model licence on its page, and paste the token into Configure → Flux Model.
• The download failed part way. Tick Force fresh re-download and load again.

Library Search returns nothing

It reads an Aegis Photo Voyager library. Without Voyager installed and a library built there is nothing to search. Photos that were deleted or hidden in Voyager are deliberately excluded from results.

Voice input does not work

Dictation needs the arecord utility, which is Linux only, plus a working microphone and an internet connection. "Could not understand audio" means the recording came through but the speech was not recognised; try again closer to the microphone. Recording always lasts eight seconds.

The assistant repeats itself, then stops

Local models occasionally fall into a loop and emit the same word or sentence over and over instead of finishing. When that happens the reply is cut off automatically and ends with a note saying the model began repeating itself — the same applies to the Describe, Quality and Composition tools. Nothing is broken; just ask again. If it keeps happening, try a larger or better-suited model, and check that the Context Window is not set larger than your model actually supports.

A photo will not open

JPEG, PNG, HEIC, HEIF, WebP, AVIF, TIFF and BMP are supported. Camera raw files are not. A file that fails to load shows a ❌ on its thumbnail; that usually means the file is damaged or is not really the format its extension claims.

Disk space is filling up

Each edit writes a working copy into ~/.aegisphotocommander/tmp/. Committing a photo clears out its intermediates, but a session that ends without committing leaves them behind. With the application closed, that folder can be emptied safely.

The application will not start

Only one copy runs at a time, coordinated through a local service. If another copy is already running, a new launch hands its photos to the existing window instead of opening a second one — look for a window you already have open. That service prefers port 8001; if something else is using it, the application moves to the next free port automatically, so a busy port is not a reason for it to fail to start.

Reporting a problem

Start the application with --debug to get verbose logging. Logs are written to ~/.aegisphotocommander/tmp/, with model conversations in llm.log. That log is reset each time the application starts, so collect it before restarting.

Contact Support