Layerhand

An AI retoucher that drives Photopea while you watch and returns a layered, editable PSD instead of a flat JPEG, on the web or through MCP.
Run Locally » · Screenshots · Report a Bug

Table of Contents

Expand

1. About The Project
   • Screenshots
   • How It Works
   • Features
   • Architecture
   • Tech Stack
2. Getting Started
   • Prerequisites
   • Installation
3. Roadmap
4. Team
5. License
6. Acknowledgments

About The Project

AI retouching that returns a layered PSD, not a flat JPEG. Layerhand retouches a photograph inside Photopea, a real image editor, while you watch. GPT-6 Astra operates the editor the way a retoucher would. You can type a correction mid-run. The download is a layered PSD — named layers, masks, and adjustments still editable — plus a flattened PNG preview. It is not a generated image and not a baked-in JPEG.

The product is a desktop workbench (1280 px and up) and an MCP server for Codex, Claude Code, and other hosts. Three free runs, no account. After that, paste your own OpenAI API key; it is used for that run only and never stored. Uploads are deleted within 24 hours.

Built for GPT-6 Astra Challenge, where it placed in the Top 100.

↑

Screenshots

Landing · The home page pitches a layered PSD, not a flat JPEG, with three free runs.	Workbench · Drop in a photograph, say what you want, and optionally add an OpenAI key.
Live Run · GPT-6 Astra drives Photopea while you type a correction without restarting the run.	Layered Result · Download the layered PSD and a flattened PNG preview, with every named layer listed.
MCP · Paste the setup prompt into Codex, Claude Code, or any MCP host.

↑

How It Works

1. Drop in a photograph. JPEG or PNG, up to 20 MB and 6000 px on the long edge. Arrived without one? Start from the sample bottle.

   

2. Say what you want. Plain words, up to 500 characters: brighten it, warm the colors, darken the corners. The workbench title is “Give the agent one clear direction.”

   

3. Watch it work, and correct it. GPT-6 Astra drives Photopea. Type a correction while it runs; the next steps bend, without starting over. It cannot undo a step already taken, but it can repair one.

   

4. Download the layered PSD. Every edit arrives on its own named layer, its mask and adjustment still editable. A flattened PNG comes with it to preview. Open the file in Photoshop, Affinity Photo, GIMP, or back in Photopea.

   

↑

Features

• Layered PSD output. Not a flat JPEG: named layers, editable masks, and adjustment layers.
• Live editor. GPT-6 Astra drives Photopea while you watch the live editor.
• Mid-run corrections. Corrections are acknowledged on the page, without restarting.
• Partial results. A run that hits its cap, is canceled, or stops early still returns a partial layered file.
• Free runs. Three free runs, no account; an optional OpenAI key after the allowance.
• Uploads. JPEG or PNG uploads, 20 MB / 6000 px, with a sample photograph on the workbench.
• Short retention. Uploads are deleted within 24 hours; download links expire after one hour.
• From your agent. Paste the setup prompt on /mcp into Codex, Claude Code, or any MCP host, and bring your own OpenAI key; the run still happens on Layerhand. The MCP tools are start_run, wait_run, steer_run, cancel_run, and get_result.
• Hosted install files. Served at /plugins/layerhand-mcp.tgz, /plugins/layerhand.zip, /plugins/marketplace.json, and /plugins/layerhand-mcp.js.

↑

Architecture

Made with Archify from architecture.json.

↑

Tech Stack

• Languages: TypeScript for the server, agent, editor, and page.
• Frontend: a vanilla page (apps/web/app.ts plus landing modules; no React), and three.js for the landing “Still yours to edit.” glass object.
• Backend: Bun 1.4.2 as the runtime and bundler, with bun --hot for bun run dev; Playwright (playwright-core) for Chrome over CDP in agent mode; ag-psd for Photoshop document support; and a Model Context Protocol server in packages/layerhand-mcp.
• Data: PostgreSQL and Google Cloud Storage.
• AI and services: OpenAI GPT-6 Astra through the Responses API, Photopea as the image editor the agent drives, and Browserbase for hosted Chrome.
• Infrastructure: Docker (oven/bun:1.4.2-alpine) and Cloud Run.
• Tooling: Bun's test runner for tests, and Prettier.

↑

Getting Started

Local development defaults to a fake session: no API keys, no Browserbase, in-memory database.

↑

Prerequisites

• Bun 1.4.2 — pinned by the production image (oven/bun:1.4.2-alpine) and the lockfile (version 2). Use this version for anything that talks to a browser over CDP.
• Google Chrome — or another desktop browser, with a viewport at least 1280 px wide for the workbench. Narrower screens get the “Layerhand needs a wider canvas” gate.
• Python 3 — runs the demo recorder's tests in bun run check, with the standard library only.

↑

Installation

1. Install the dependencies.

   bun install --frozen-lockfile

2. Start the dev server. bun run dev is LAYERHAND_PAGE_RELOAD=1 bun --hot apps/server/index.ts. It reloads the page on an edit under apps/web and serves it without the production security headers. The port is 3000 unless PORT is set.

   bun run dev

   RUN_MODE is fake when unset. That path runs fakeRun(): a short product-retouch script on a one-second step timer, with steer and cancel still wired.

3. Open the workbench. Open http://localhost:3000. The workbench still walks the four steps, so you can take screenshots against it. Readiness is GET /health and returns { "status": "ok", "database": "ready" } when the in-memory database has migrated.

4. Optionally, drive a real editor. Copy .env.example to .env only when you want RUN_MODE=agent or other production-like values; fake mode does not need it. To drive a real editor instead, set:

   RUN_MODE=agent
   PUBLIC_URL=http://localhost:3000
   BROWSERBASE_API_KEY=...
   OPENAI_API_KEY=...

   Agent mode refuses to start without BROWSERBASE_API_KEY and PUBLIC_URL. scripted runs the real agent loop against a recorded editor and a scripted model, still without a live browser.

5. Try MCP locally. With the dev server up, open http://localhost:3000/mcp. The setup prompt and the Codex / Claude Code / other manuals use that origin. The five tools are start_run, wait_run, steer_run, cancel_run, and get_result.

6. Run the checks. bun run check runs the lint, the typecheck and the tests, including the MCP package's and the demo recorder's Python tests. bun run build builds the production bundle separately.

   bun run check

   RUN_BROWSER_TESTS=1 runs the fake-backed page tests in installed Google Chrome.

↑

Roadmap

See open issues for a full list of proposed features (and known issues).

↑

Team

Made with contrib.rocks.

↑

License

See LICENSE for more information.

↑

Acknowledgments

• Photopea — the editor Layerhand drives; Layerhand is not affiliated with it.
• GPT-6 Astra Challenge — OpenAI × Product Hunt.
• Hugeicons — icon font on the landing and workbench.
• Canvas UI — glass object on “Still yours to edit.”
• Archify
• contrib.rocks
• Shields.io

↑