Skip to content

Open source

Blur Studio

Born from a launch-day emergency: a client's 1,000+ photo gallery needed every face blurred except her own, with no time for a manual pass or a third-party retoucher. Coordinate-based selective blurring — precise, non-generative, keeps VIP subjects sharp — shipped overnight as a glass-UI web app, a CLI, and an MCP server that AI agents can drive directly.

Role
Creator · Solo build
Period
2026 — present
Stack
React 19 · Vite 6 · Tailwind v4 · Express · and 5 more
Place
OSS, MIT licensed
Blur Studio — ellipse targets, a VIP exclusion box (dashed green), and the paint grid, all live on a real photo.

Blur Studio — ellipse targets, a VIP exclusion box (dashed green), and the paint grid, all live on a real photo.

1,000+photos in the launch gallery

A client launching her brand had a photo gallery ready to go — well over a thousand images — except almost every one had faces in it that couldn't be published, with exactly one exception: hers. She's the face of the business; everyone else in every shot needed to disappear before launch, or the gallery was dead weight.

01 / 03

The problem

Hiring a retoucher or masking a thousand-plus photos by hand wasn't realistic against the launch date.

Generative retouching (Nanobanana) was tried first — but blurring by regenerating the region meant the photos stopped being real photos: likenesses drifted, backgrounds shifted, and the one thing the gallery needed to stay was reality.

What the problem actually called for was surgical, coordinate-exact control — blur everyone else, leave her untouched — running across a folder too large to touch by hand, in the hours left before launch.

A fresh session, config restored from disk — every saved region reloads exactly where it was left.
02 / 03

What it does

  • Four contextual tools. Grid paint, ellipse, VIP exclusion box, and pan — switchable by click or number key, with full undo/redo across every loaded image.
  • VIP exclusion boxes. Rectangular "stay sharp" zones that punch through any overlapping blur region — the exact feature the launch needed, generalized: one subject stays crisp in a crowd of blurred faces.
  • Four view modes. Blurred, Original, Split, and Mask — see exactly what the blur mask covers before committing to it.
  • Batch processing. Apply saved regions across an entire folder in one pass, with a live per-image progress list and one-click zip download.
  • Non-destructive by default. Output writes to a separate folder unless in-place replacement is explicitly chosen — and even then, the original is backed up first.
Mask view — the feathered blur falloff and the hard-edged exclusion box, made visible before committing.
03 / 03

Built overnight, agent to agent

The build itself was agentic end to end: Gemini 3.7 Flash and Claude (Opus and Sonnet) wrote the tool, and the same Claude Code harness driving the build tested it by calling the project's own Skill and MCP server directly — the identical interface an agent would use in production. The tool proved itself by using itself before a human ever opened the web UI.

Detection is the LLM's job and blurring is the engine's. Each photo is dissected into a grid an LLM can count, so the model names exactly which blocks need blurring, then calls the tool, and the Python server blurs those blocks precisely. Keeping the server and the UI side by side meant any photo too complex for the model got a human override in the same tool.

The web UI, the CLI, and the MCP server are three thin wrappers around one function library — none of them talk to the Python image engine directly, and none of them know more than the others. A manual pass through the web UI handled the one face that had to stay exactly as it was; the rest of the gallery ran through the batch path unattended.

What started as a launch-blocking, thousand-plus-photo emergency closed out as an overnight delivery — crisis to shipped, tested tool inside the hours before launch. Afterward, the one-client fix was generalized and open-sourced under MIT, because the shape of the problem — one face to protect, a crowd to blur, too many photos for a manual pass — was never going to be a one-time need.

Decisions and why

  1. No automatic face or plate detection — coordinates only.

    WhyThe generative alternative had already failed the actual test: regenerating pixels to hide a face made the photo less real, which was the one thing the gallery could not afford. Exact coordinates preserve every pixel outside the marked region, and they let a human and an agent drive the identical engine with identical guarantees.

  2. One function library behind three front ends.

    WhyblurService.js is the single source of truth for the web UI, the CLI, and the MCP server. A new capability only has to be built once to reach all three — which is what made same-night batch processing possible on top of a same-night manual-review UI.

Technical highlights

  • 07

    Multi-target Docker build — one Dockerfile, two images (web app on :3333, MCP server over stdio) sharing a Node + Python/Pillow base.

  • 01

    Built agentically under launch-night time pressure — Gemini 3.7 Flash and Claude (Opus, Sonnet) writing the tool, Claude Code testing it live over its own Skill and MCP server before a human touched the UI.

  • 02

    Grid dissection for LLM targeting: each photo is split into countable blocks, the model names the blocks to blur and calls the tool, the Python server applies the blur, and the UI stays on hand for human override on complex shots.

  • 03

    Coordinate-based blur engine (blurService.js → blur_processor.py, Pillow) shared identically across the web UI, CLI, and MCP server — no front end talks to Python directly.

  • 04

    Feathered Gaussian blur with per-target radius overrides, plus rectangular exclusion boxes that punch through overlapping blur regions.

  • 05

    MCP server (StdioServerTransport) exposing 6 tools for direct agent control — scan_folder, get_config, save_image_config, apply_blur, export_python_snippet, list_presets.

  • 06

    48 Playwright end-to-end tests drive the real running app in headless Chromium, covering every tool, view mode, and real Apply, Batch and Download flows.

Impact

  • Turned a launch-blocking, thousand-plus-photo gallery into a same-night deliverable — no third-party retoucher, no missed launch date.
  • Generalized a one-client emergency into a reusable, MIT-licensed tool: the one-face-sharp, everyone-else-blurred, too-many-photos-for-hand problem was never going to be a single client's problem alone.
  • Gives privacy-conscious teams (real estate, journalism, HR) exact control over what stays sharp, instead of trusting a detection model's best guess.
Outcomes

By the numbers.

6 MCP tools
agent-drivable end to end
Overnight
crisis to shipped tool
Visit project

See it in the wild.

This case study covers how Blur Studio was built — these links open what ships today: the live product, repo, demos, and supporting material.

Recent activity

The changelog.

August 2026
Aug 2026
shipped:Blur Studio — image Blur Studio: privacy-clean baseline3 commits · Aug 2026
GitHub ↗
↗ Next case study

agent-team

Say "set up the team" and agent-team scans the repository, sizes it, and offers three teams, lean, recommended and full, with every seat citing the evidence that raised it. Each seat is a session with its own rulebook and its own workers, and the seats talk through a fixed message protocol (ASK, HANDOFF, RESULT and more). Later, "re-evaluate the team" counts each seat's commits, worker runs, inbox and blocked lines, re-scans the repo, and proposes adding, retiring, merging or splitting seats. Nothing changes without the owner's yes.