darktable Agentic: an AI copilot for RAW photo editing

Why this exists

darktable is deep, and most of us use the part we learned first

A conversation partner that knows the whole surface changes which tools you reach for.

darktable has a genuinely deep toolset, and most photographers work with a comfortable fraction of it. A collaborator that knows the rest can say "that halo is the local contrast module, not the tone curve", or "for this you probably want the tone equalizer rather than pushing shadows in exposure", and then show you what that looks like. The practical win is not that the work gets done for you. It is that you end up using more of what darktable can actually do.

You describe the outcome, not the control. "Warm it up, but keep the shadows neutral" is one sentence. Doing it is white balance plus color balance rgb, plus knowing which of the four-way sliders is shadows. You say the thing you want, and the AI tells you which control it reached for, so next time you know too.

Why the enabling work had to happen in C

Stock darktable's Lua API cannot support this. It exposes images, films, tags, styles, storages and GUI actions, but not the live develop state: no module parameters, no history, no masks, no way to read back what the pixelpipe just produced. The available workarounds are all dead ends for an agent:

• darktable-cli never loads the user's library and cannot touch a live darkroom.
• dt.gui.action drives GUI widgets, which means single-image, focus-dependent, GUI-only, and it gives no readback of values or bounds.
• Writing XMP sidecars or poking library.db bypasses the running instance entirely, so you see nothing until a reload.

So the fork adds a darktable.develop Lua namespace in C: introspection-driven read and write of any module's parameters, masks, and a live uncommitted preview grab. That is what turned "click a slider through the GUI automation layer" into "read the real parameter, clamp against its real bounds, write it, reprocess".

What it can do

Conversational RAW editing, masks, retouch and culling

Every capability below acts on the photo currently open in your darkroom, through typed tools, with the result rendered back so the AI can judge it.

What a session looks like

One small reversible step at a time

Bracketed names are the tool calls the AI made. Every one of them landed in the darkroom that was already open on screen.

That is the record of who did what. Every entry the AI added is right there, in your own history stack, and removable. You can interrupt mid-thought, disagree, take the mouse and finish the mask yourself. If you stop talking, nothing else happens.

Culling and triage

A second pair of eyes on a whole roll

Before any editing decision, the AI can act as a curator: it looks at the shoot as a grid, says what it sees, and you decide what gets a rating.

Talk about a shoot without opening frames one at a time

One call renders a single labelled grid image from whatever collection is open in your lighttable, 25 photos in 5 columns by default, each cell carrying the filename, the image id and the current rating. The AI looks at that sheet and tells you what it sees: near-duplicates, the sharpest frame of a burst, the one where the eyes are open. Then you decide.

Ratings, tags and notes are separate, explicit calls, so nothing is applied until you say so. Contact sheets themselves are strictly read-only: they never touch ratings, tags, history or the darkroom. Notes land in the photo's Description field, so the AI's reasoning shows up in darktable itself and survives in the sidecar. You can disagree with it later and still see what it thought.

Then work through the roll without reaching for the mouse

Stepping to the next or previous photo in the open collection uses the same ordering as the contact sheet, and opens it in darkroom. Combined with the editing loop, "same idea on the next one, then show me" is a single turn, and you are still looking at every frame as it comes up. It errors at either end of the collection instead of wrapping around, so a walk through a shoot terminates cleanly.

Rating straight off the card, before importing anything

When darktable does not know about the shoot yet, there is a file-based path that needs no library and no GUI. It pulls auto-rotated JPEG previews plus EXIF out of the RAWs, the AI looks at them and proposes ratings, those ratings are written as XMP sidecars next to the RAWs, and only then does the GUI launch with the folder as a film roll, pre-filtered to the rating range you asked for. No SQLite poking, no half-imported state.

This is the one genuinely batch-shaped workflow in the project, and it is deliberately confined to triage, before any editing decision, with the GUI as the last step so you review the result yourself.

How it works

Three processes, and a file bridge into your running darktable

Your MCP client talks to a Python server, the server talks to a Lua worker loop living inside the darktable you already have open, and that worker calls C bindings that mutate the live pixelpipe.

Which clients it works with, and running it over the network

darktable-mcp is a standard Model Context Protocol server, not a client-specific plugin, so anything that speaks MCP can drive it. It is developed and used against Claude Desktop and Claude Code, and any other MCP-capable client connects the same way. What differs between clients is which model ends up seeing your session, and that is your choice, not the server's.

stdio is the default and the recommended local setup: the client starts the server as a child process on the same machine. For a client running elsewhere, the same server also speaks Streamable HTTP with a bearer token, bound to a host and port, so it can be reached over the network from another machine. Put it behind a TLS reverse proxy with buffering off.

One thing that does not change either way: darktable is still open in front of somebody. The transport moves where the client runs, not where the editing happens.

Two models at once, one editing and one giving a second opinion

More than one client can be connected at the same time. The bridge is a directory of request and response files, and the worker loop inside darktable picks up every pending request in turn and answers each one by its own id, whichever client wrote it. That makes a genuinely useful split: one model doing the edits, another looking at the photo you currently have open and telling you what it thinks of it, as a curator rather than an operator.

What the bridge does not do is isolate them. There is no per-client session: every call acts on whichever image darktable has open at that moment. One client editing and another observing behaves well. Two clients both making changes can surprise each other, because the second one inherits whatever the first just did, including a move to a different photo. Viewport snapshots already refuse to write when darkroom has moved on, but that is a guard on one class of mistake, not general isolation.

Why a long-running plugin and a file bridge, not a CLI shell-out

There is no headless one-shot path for library reads and writes. darktable-cli does not load your library, and darktable --lua brings up the full GUI. So the design is a long-running plugin inside your interactive session, plus a file bridge, rather than a command-line invocation per call. That constraint happens to align exactly with the design goal: the session you are sitting in front of is the session being edited. Nothing is prepared behind your back and presented as finished.

Install

Two pieces: a patched darktable, and the MCP server

Stock darktable cannot expose its live darkroom state, so both halves have to be in place. Install the newest pair from the releases page.

sudo apt install ./darktable-agentic_*_amd64.deb   # patched darktable
sudo apt install ./darktable-mcp_*_amd64.deb      # the server, venv included

mkdir -p ~/.config/darktable
cat /usr/share/doc/darktable-agentic/luarc.snippet >> ~/.config/darktable/luarc

darktable -d lua 2>&1 | grep -i mcp     # must print: darktable-mcp bridge: ready

claude mcp add darktable /usr/bin/darktable-mcp

{
  "mcpServers": {
    "darktable": {
      "command": "/usr/bin/darktable-mcp",
      "args": []
    }
  }
}

git clone --recurse-submodules -b agentic-mcp \
  https://github.com/rfordinal/darktable-agentic.git
cd darktable-agentic
./build.sh --prefix /opt/darktable-agentic --build-type Release --install --sudo

git clone -b agentic-mcp https://github.com/rfordinal/darktable-mcp
cd darktable-mcp
uv venv --python 3.12 .venv
uv pip install -p .venv/bin/python -e .

darktable-mcp install-plugin   # copies the plugin, adds the require line to luarc

darktable-mcp install-sidecar

DTMCP_BEARER_TOKEN=... DTMCP_PUBLIC_URL=https://your.host \
  darktable-mcp --http --host 127.0.0.1 --port 8787 --path /mcp

Status and maturity

What is solid, and what is not

Reproduced from the project's own README, per layer, unedited in substance. A page that hides the rough parts is not worth reading.

This is a working tool used by its author on real photographs, not a released product with a support matrix. Expect to read error messages.

Safety and non-destructive behavior

You remain in control

• Nothing is committed behind your back. Parameter writes go into the in-memory history stack and reprocess. They are not written to library.db or XMP until darktable saves normally, and Ctrl+Z reverts the AI's changes like any other edit.
• Nothing happens unprompted. The AI acts only inside a turn you started. There is no background pass over your library, no scheduled processing, no queue.
• Rendering a preview never writes. It grabs the live pipeline output, so it is safe to call as often as you like.
• Typed tools only. The AI never gets raw Lua or shell evaluation. The Lua bridge dispatches from a fixed method whitelist, and unknown methods error.
• No direct database access, ever. Only official darktable APIs: darktable-cli for export, the Lua API for everything else. Any contribution that reads or writes library.db directly is rejected.
• Edits from a snapshot stay on that photo. A viewport snapshot records the image id, and a placement is refused when darkroom has moved on, because a coordinate from one frame means nothing on another.
• Failed local edits roll back. The mask tools clean up any module instance they created if a later step fails, so you never get an orphan instance in your history.
• Working on a duplicate is still your call. Live editing mutates the open image's real history stack. For experimental sessions, duplicate the image in darktable first.

FAQ

Questions people actually ask about AI photo editing in darktable