Skip to main content
Glama

LazyRoom

An AI-native, cross-platform image toolbox — built so AI agents can do everything a human can, with a beautiful desktop app on top.

LazyRoom is a desktop equivalent of ImageToolbox for Linux and Windows, re-architected around one principle: the AI agent is the primary user. Every capability is a documented, validated operation that agents reach through MCP, a headless CLI or a Python SDK. The Material 3 desktop GUI is just another client of the same engine.

  • 600+ operations — photographic adjustments (exposure, white balance, curves, HSL, colour-grading wheels, split toning, fade, LUTs, dehaze, clarity…), effects (grain, bloom, halation, diffusion, vignette…), geometry (crop, 49 resampling kernels × 19 scaling colour spaces, perspective, straighten…), text/watermarks/annotations, and all 520 ImageToolbox filters across 14 groups — ported from the original sources (see docs/FILTER_PARITY.md).

  • Non-destructive projects — ordered steps with masks (radial, gradient, brush, luminance/colour/skin ranges, AI subject), opacity and blend modes; groups; undo/redo shared by humans and agents; open JSON format.

  • Reference style matching — "make photo A look like photo B": fits an editable grade (white balance, tone curve, 3-way grading, saturation, HSL, grain, vignette), reports confidence and limitations, and beats classic colour transfer by ~2.6× in a ground-truth benchmark (docs/STYLE_MATCHING.md).

  • Natural-language looks — semantic presets (70s film, teal & orange, Polaroid, faded analog, editorial portrait, urban, earthy…) and a transparent intent planner; optional local/remote LLM backends.

  • Batch processing — folders/globs, per-image normalisation for consistent series, per-file status, JSON reports, cancellation, resume.

  • Utility tools — palette, OCR, QR/barcodes, collage, stitch, stack, HDR fusion, focus stacking, panorama, metadata edit/strip, duplicates, animations, PDF, compress-to-size, SVG tracing, textures, fractals, …

  • Local-first & safe — originals never modified, no silent overwrites, path policy, untrusted metadata never treated as instructions, no network unless you opt in.

Install

# from source (Python 3.11–3.13)
git clone https://github.com/adit-0132/LazyRoom.git && cd LazyRoom
python -m venv .venv && . .venv/bin/activate           # Windows: .venv\Scripts\activate
pip install -e ".[all]"                                # GUI, RAW, AI, HEIF, HTTP extras
# optional system tools
sudo dnf install gmic tesseract   # Fedora  (Ubuntu/Debian: sudo apt install tesseract-ocr)
# G'MIC 3.x or 4.x is needed for the G'MIC-based filters. Ubuntu/Debian's own gmic package can be the old
# 2.x series: install the current .deb from https://gmic.eu/download.html instead (Windows: the CLI zip).

Pre-built bundles: LazyRoom-<version>-x86_64.AppImage (Linux) and the Windows installer / portable ZIP built by CI (see DEVELOPMENT.md).

Related MCP server: photocop

Use it

Desktop: lazyroom-gui [photo.jpg] — drag & drop a photo, pick tools from the rail, adjust in the right panel, compare before/after (\), ask the AI panel ("faded 1990s magazine look"), export (Ctrl+E).

Agents (MCP): register once — claude mcp add lazyroom -- lazyroom-mcp (other clients: lazyroom agent-setup). Then ask your agent things like "Give ~/Pictures/beach.jpg a warm, faded 1970s film look and save it next to the original". See AGENT_INTEGRATION.md and MCP_REFERENCE.md.

CLI:

lazyroom ops list --category adjust
lazyroom apply in.jpg out.jpg --op adjust.white_balance temperature=20 --op effect.grain amount=15
lazyroom style match photo.jpg reference.jpg --export matched.jpg
lazyroom batch ./shoot --output-dir ./graded --preset faded-analog --normalize both

Full reference: CLI_REFERENCE.md.

Python:

from lazyroom import LazyRoom
pm = LazyRoom()
p = pm.project_create("photo.jpg")["project_id"]
pm.preset_apply(p, "teal-orange", strength=0.8)
pm.export(p, "photo-teal.jpg")

Documentation

ARCHITECTURE.md

Layers, decisions, colour pipeline, security model

FEATURES.md

Feature parity with ImageToolbox and the directive (status, tests, platforms)

docs/FILTER_PARITY.md

All 520 ImageToolbox filters, one by one

docs/OPERATIONS.md

Every operation and its parameters

AGENT_INTEGRATION.md · MCP_REFERENCE.md · CLI_REFERENCE.md

Interfaces

docs/PROJECT_FORMAT.md · docs/STYLE_MATCHING.md · docs/SECURITY.md · docs/MODELS.md

Specs

DEVELOPMENT.md · TESTING.md · STATUS.md

Contributing, tests, current status

LICENSE · NOTICE · docs/THIRD_PARTY.md

Licences

License

Apache License 2.0. LazyRoom ports algorithms from ImageToolbox, ImageToolboxLibs and Trickle (Apache-2.0, T8RIN), aire and related crates (MIT/BSD/Apache, awxkee), GPUImage, jhlabs and others — see NOTICE and docs/THIRD_PARTY.md. AI model weights are never bundled; each has its own licence (docs/MODELS.md).

Available Tools

27 tools
analyze_styleB
Read-onlyIdempotent

Detailed photographic style measurements of a (reference) image incl. tone histogram and grain size.

Inputs: path (required).

apply_presetC

Add a preset as an editable group step (strength = group opacity 0..1).

Inputs: preset_id (required), project_id (required), mode, strength.

apply_to_fileB

One-shot: apply steps (or a preset id) to an image file and export, without keeping a project.

Inputs: input (required), output (required), steps, format, +4 more.

cancel_jobB

Cancel a running job; finished outputs are kept.

Inputs: job_id (required).

compare_versionsB
Read-onlyIdempotent

Metrics (ΔE, SSIM, PSNR, colour-distribution distance) between two versions + side-by-side image.

Inputs: project_id (required), a, b, include_image.

delete_presetA
Destructive

Delete a user preset. Destructive: ask the user first, then call with confirm=true.

Inputs: preset_id (required), confirm.

describe_operationsA
Read-onlyIdempotent

Full documentation for 1-50 operation ids: parameters with types, ranges, units, defaults, JSON schema, whether it can be masked, and examples.

Inputs: ids (required).

describe_toolC
Read-onlyIdempotent

Parameter schema and documentation of a utility tool.

Inputs: name (required).

edit_projectA

Apply edit actions atomically (all-or-nothing, one undo step). Action shapes: {"type":"add","op":ID,"params":{...},"index"?,"mask"?,"opacity"?,"blend"?,"label"?} {"type":"add_group","steps":[{op,params,...}],"label"?,"mask"?,"opacity"?} {"type":"update","step_id":ID,"params":{...merged},"mask"?,"opacity"?,"blend"?,"enabled"?} {"type":"remove"|"duplicate","step_id":ID} {"type":"move","step_id":ID,"index":N} {"type":"toggle","step_id":ID,"enabled"?} {"type":"set_steps","steps":[...]} {"type":"clear"} Mask example: {"shapes":[{"type":"radial","center":[0.5,0.4],"radius":[0.3,0.35],"feather":0.6}, {"type":"luminance","min":0,"max":0.4,"mode":"intersect"}]} (types: all, rect, ellipse, radial, linear, polygon, brush, luminance, color, hue, skin, image, subject).

Inputs: actions (required), project_id (required), description.

export_imageB

Render at full resolution and write a NEW file (originals are protected; existing files need overwrite=true). Formats: jpg png webp avif heic tif bmp gif jp2 qoi ico tga pdf.

Inputs: output (required), project_id (required), format, dry_run, +5 more.

get_capabilitiesA
Read-onlyIdempotent

Manifest: operation categories/counts, edit-action types, mask types, formats, optional backends, security policy, workflows and error codes. Call once at the start of a session.

Inputs: no named parameters.

get_project_stateB
Read-onlyIdempotent

Complete editing state: ordered steps with ids, params, masks, opacity, blend; undo/redo availability.

Inputs: project_id (required), include_history.

inspect_imageB
Read-onlyIdempotent

Metadata and measured style of an image file: tone (median lightness, black/white points, contrast), colour cast / estimated white balance, zone tints, saturation, grain, vignette, palette, descriptors. include_thumbnail returns a small preview image.

Inputs: path (required), include_thumbnail.

job_statusA
Read-onlyIdempotent

Status/progress of a job (optionally wait up to wait_seconds), or all jobs when job_id is omitted.

Inputs: job_id, wait_seconds, include_items.

list_operationsB
Read-onlyIdempotent

Compact list of editing operations (id, title, group). Filter by category, ImageToolbox filter group (e.g. category='filter', group='blur') or keyword query (e.g. 'vignette', 'film grain', 'pixelate').

Inputs: group, limit, query, offset, +1 more.

list_presetsC
Read-onlyIdempotent

Built-in semantic looks (e.g. warm-70s-film, teal-orange, vintage-polaroid, faded-analog, cool-urban, earthy-muted, warm-editorial-portrait, bw-classic) and user presets. Search by mood words.

Inputs: kind, query.

list_toolsC
Read-onlyIdempotent

Utility tools that produce data or new files: palette, histogram, compare, duplicates, metadata read/write/strip, QR/barcode generate/read, OCR, split, stitch, collage, stack, HDR, focus stack, panorama, gradients, noise, animations, PDF, compress to size, ASCII, SVG trace, rename...

Inputs: query.

match_styleA

Fit an editable grading pipeline (white balance, tone curve, 3-way colour grade, saturation, HSL, grain, vignette) that gives the project the look of a reference photo. matching='look' transfers the grade without copying scene content; 'exact' matches the reference statistics (same scene). strength=null uses a confidence-based strength. Returns the steps and a report: similarity, confidence, limitations.

Inputs: reference (required), project_id (required), mode, apply, +5 more.

open_imageA

Open an image as a new non-destructive editing project. Returns project_id and state.

Inputs: path (required), name.

open_projectC

Open a saved .lazyroom project (e.g. one a human edited in the GUI).

Inputs: path (required).

plan_editB

Translate a natural-language request ('warm faded 70s film, muted greens, subtle grain') into editable steps using the built-in rule engine (or a configured local/remote LLM). Review, then apply.

Inputs: request (required), apply, project_id.

project_historyB

List history, undo/redo N steps, or revert to a history entry (revert is itself undoable).

Inputs: project_id (required), steps, action, history_id.

render_previewA
Read-onlyIdempotent

Render the project (or an earlier version: 'original' or a history id) and return the preview image, per-step timings and result statistics. compare='side_by_side' shows before | after.

Inputs: project_id (required), compare, version, max_size, +1 more.

run_toolB

Run a utility tool (see list_tools/describe_tool). Destructive tools require confirm=true in params.

Inputs: name (required), params (required).

save_presetB

Save a reusable preset from a project's pipeline or explicit steps.

Inputs: name (required), tags, steps, overwrite, +2 more.

save_projectB

Save the project as human-readable JSON (.lazyroom) that the GUI, CLI and other agents can open.

Inputs: project_id (required), path.

start_batchA

Process files/folders/globs with one pipeline in the background. Returns job_id immediately; poll job_status. normalize equalises exposure/WB per image for consistent series; match_reference adds a per-image style match. Failures are isolated per file; a JSON report is written to output_dir.

Inputs: inputs (required), output_dir (required), steps, format, +11 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 27 tools

    Disambiguation4/5

    The set has a clear layered architecture: discovery (get_capabilities/list_operations/describe_operations), project lifecycle (open/get_state/edit/history/render/export/save), style (analyze_style/match_style/presets), batch (start_batch/job_status/cancel_job), and a meta-tool layer (list_tools/describe_tool/run_tool). Most tools target a distinct resource+action, but a few pairs are easy to confuse: inspect_image vs analyze_style (both measure tone/colour/grain), and apply_preset vs match_style vs plan_edit all "add steps that create a look". The generic compare utility inside list_tools also overlaps compare_versions.

    Naming Consistency4/5

    The dominant pattern is verb_noun (open_image, edit_project, render_preview, apply_preset, delete_preset, list_presets, match_style), which is easy to generalize from. Deviations are minor: two noun-phrase names (project_history, job_status) and an action/noun split in the batch family (start_batch, cancel_job, job_status). Readable throughout, just not perfectly uniform.

    Tool Count3/5

    27 tools is heavy for a single server and sits above the comfortable 3-15 band. The count is partly mitigated by the meta-tool consolidation (list_tools/describe_tool/run_tool fold dozens of utilities into three entries), but the project/preset/style/batch surface still exposes a lot of individual endpoints an agent must choose among.

    Completeness4/5

    Coverage is broad: open (image or .lazyroom), inspect, edit atomically, history/undo/revert, preview, full-res export, save, presets CRUD, style analysis and matching, batch processing with progress/cancel, and a capabilities manifest. Remaining gaps are modest: no explicit close/discard/delete-project operation, and no direct 'add step by operation id without params lookup' shortcut, but agents can work around both.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to process images locally via file paths—converting, resizing, removing backgrounds, smart cropping, upscaling, reading or stripping metadata, and batch processing—without files ever leaving the device.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables external AI agents to programmatically inspect, edit, and export image documents through tools for layers, selections, painting, adjustments, masks, history, and compositing.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to run cross-platform batch photo-processing workflows—including RAW decoding, adjustments, noise reduction, white balance, LOG restoration, EXIF tagging, deduplication, selection, HTML galleries, folder watching, and presets—through a unified versioned JSON contract. It also exposes MCP tools for processing, suggestions, autopilot, indexing, search, selection, HDR, face blurring, and more.
      MIT
    • A
      license
      C
      quality
      C
      maintenance
      Enables AI agents and users to edit images through natural language, performing layered, non-destructive operations like masks, clipping masks, blend modes, filters, generative fill, image-to-image, background removal and upscaling, either locally or via the user's own API keys. Agents can preview rendered results, measure image properties, review their own work and export finished images through 62 tools shared with the editor's UI.
      62
      46 PyPI
      9
      MIT