kokon

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/brand/logo/kokon-logo-white.svg">
    <img src="assets/brand/logo/kokon-logo.svg" alt="Kokon" width="300">
  </picture>
</p>

<h3 align="center">Edit photos by describing the change, on your own computer.</h3>

<p align="center">
  One installer for Windows and Mac, no Python, no cloud. Powered by Qwen-Image 2.1, and ready for your AI agent.
</p>

<p align="center">
  <a href="https://github.com/GabrieleLozupone/kokon/releases/latest"><img src="https://img.shields.io/github/v/release/GabrieleLozupone/kokon?style=flat-square&labelColor=333&color=6b6b6b&label=release&cacheSeconds=3600&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjQzI5N0ZGIiBzdHJva2Utd2lkdGg9IjIuNCIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIj48cGF0aCBkPSJNMTIuNiAyLjZBMiAyIDAgMCAwIDExLjIgMkg0YTIgMiAwIDAgMC0yIDJ2Ny4yYTIgMiAwIDAgMCAuNiAxLjRsOC43IDguN2EyLjQgMi40IDAgMCAwIDMuNCAwbDYuNi02LjZhMi40IDIuNCAwIDAgMCAwLTMuNHoiLz48Y2lyY2xlIGN4PSI3LjUiIGN5PSI3LjUiIHI9IjEuMiIgZmlsbD0iI0MyOTdGRiIvPjwvc3ZnPg%3D%3D" alt="Latest release"></a>
  <a href="https://github.com/GabrieleLozupone/kokon/releases"><img src="https://img.shields.io/github/downloads/GabrieleLozupone/kokon/total?style=flat-square&labelColor=333&color=6b6b6b&cacheSeconds=3600&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjM0ZCOTUwIiBzdHJva2Utd2lkdGg9IjIuNCIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIj48cGF0aCBkPSJNMTIgM3YxMiIvPjxwYXRoIGQ9Im03IDEwIDUgNSA1LTUiLz48cGF0aCBkPSJNNCAyMWgxNiIvPjwvc3ZnPg%3D%3D" alt="Downloads"></a>
  <img src="assets/readme/badges/windows.svg" alt="Windows 10 and 11">
  <img src="assets/readme/badges/macos.svg" alt="macOS 26 or newer">
  <br>
  <img src="assets/readme/badges/nvidia.svg" alt="NVIDIA, 12 GB of VRAM or more">
  <img src="assets/readme/badges/amd.svg" alt="AMD, 12 GB of VRAM or more, beta">
  <img src="assets/readme/badges/intel.svg" alt="Intel Arc, 12 GB of VRAM or more, beta">
  <img src="assets/readme/badges/apple.svg" alt="Apple Silicon, 32 GB of unified memory recommended, beta">
  <br>
  <a href="#use-it-from-your-ai-agent"><img src="assets/readme/badges/mcp.svg" alt="MCP server included"></a>
  <a href="LICENSE"><img src="assets/readme/badges/license.svg" alt="License: AGPL-3.0"></a>
  <a href="https://github.com/GabrieleLozupone/kokon/stargazers"><img src="https://img.shields.io/github/stars/GabrieleLozupone/kokon?style=flat-square&labelColor=333&color=6b6b6b&cacheSeconds=3600&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjRjVDNTE4IiBzdHJva2Utd2lkdGg9IjIuNCIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIj48cGF0aCBmaWxsPSIjRjVDNTE4IiBkPSJNMTIgMi41bDIuOSA2IDYuNi45LTQuOCA0LjYgMS4yIDYuNUwxMiAxNy40bC01LjkgMy4xIDEuMi02LjVMMi41IDkuNGw2LjYtLjl6Ii8%2BPC9zdmc%2B" alt="Stars"></a>
  <a href="https://mcpservers.org/servers/gabrielelozupone/kokon"><img src="https://mcpservers.org/badge.svg" alt="Listed on mcpservers.org"></a>
</p>

<p align="center">
  <a href="https://kokon.app/">Website</a> ·
  <a href="#install">Install</a> ·
  <a href="#what-you-can-do">Features</a> ·
  <a href="#examples">Examples</a> ·
  <a href="#use-it-from-your-ai-agent">AI agents</a> ·
  <a href="#faq">FAQ</a> ·
  <a href="https://kokon.app/prompt-guide/">Prompt guide</a> ·
  <a href="docs/engineering-notes.md">How it works</a>
</p>

https://github.com/user-attachments/assets/8851c580-99b9-432a-82be-b6d42fa9a749

<p align="center"><a href="https://youtu.be/ulMVqrhrn-w">Watch in 4K on YouTube</a></p>

<p align="center">
  <a href="https://github.com/GabrieleLozupone/kokon/releases/latest"><picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/readme/download-windows-dark.svg">
    <img src="assets/readme/download-windows-light.svg" alt="Download for Windows" height="52">
  </picture></a>
  <a href="https://github.com/GabrieleLozupone/kokon/releases/latest"><picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/readme/download-macos-beta-dark.svg">
    <img src="assets/readme/download-macos-beta-light.svg" alt="Download for macOS (Apple Silicon, beta)" height="52">
  </picture></a>
  <a href="#roadmap"><picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/readme/download-linux-dark.svg">
    <img src="assets/readme/download-linux-light.svg" alt="Linux: coming soon" height="52">
  </picture></a>
  <br>
  <sub>Free and open source · about 12 GB of models downloaded on first run · nothing leaves your computer</sub>
</p>

---

## Why Kokon

<table>
  <tr>
    <td width="33%" valign="top">
      <h3>✍️ Just describe it</h3>
      “Remove all the people from the beach.” “Make it golden hour.” Kokon picks the mode, the
      resolution and the memory settings for you. There are no sliders to learn.
    </td>
    <td width="33%" valign="top">
      <h3>🔒 Private by design</h3>
      Everything runs on your own GPU. No account, no uploads, no telemetry, no limits. After
      setup, Kokon only checks once a day for a new version (you can turn that off). A private
      mode keeps nothing at all.
    </td>
    <td width="33%" valign="top">
      <h3>📦 One installer</h3>
      A native app built on <a href="https://github.com/leejet/stable-diffusion.cpp">stable-diffusion.cpp</a>.
      No Python, no ComfyUI, no node graphs. The first run detects your graphics card or your
      Mac's memory and downloads the right model, then verifies it. Updates install in one click.
    </td>
  </tr>
  <tr>
    <td width="33%" valign="top">
      <h3>🎯 Edits that stay in place</h3>
      Paint over an area and choose Change, Remove, Replace or Add. Kokon shows the model
      exactly where to work, so the rest of the photo stays untouched.
    </td>
    <td width="33%" valign="top">
      <h3>🖼️ Full-size results</h3>
      Kokon keeps your photo's size and aspect ratio, and enlarges with an AI upscaler
      instead of blurry resizing. It also opens iPhone HEIC photos, HDR included.
    </td>
    <td width="33%" valign="top">
      <h3>🤖 Works with your AI agent</h3>
      A built-in MCP server and local HTTP API let Claude, Cursor or your own scripts create
      and edit images on your machine.
    </td>
  </tr>
</table>

## Examples

<p align="center">
  <img src="docs/media/examples/fatto-in-casa.jpg" alt="A grandmother sprinkles parmesan over a miniature Colosseum made of pasta, standing on a tomato sauce river on her kitchen table, with Rome's rooftops at sunset through the window" width="860">
  <br>
  <sub>One project, six steps in Kokon: generate the Colosseum, rebuild it out of pasta,
  add a tomato sauce river, generate the kitchen, combine the two, expand to 21:9.</sub>
</p>

Every image below was made by Kokon itself (no stock photos), first try with that seed. Prompts,
seeds and times are in [marketing/showcase/PROMPTS.md](marketing/showcase/PROMPTS.md).

| | |
| :---: | :---: |
| <img src="docs/media/examples/remove.jpg" alt="A red scooter removed from a café street"><br>**Remove** · paint the scooter · *“the red scooter”* | <img src="docs/media/examples/replace.jpg" alt="An armchair replaced by a green sofa"><br>**Replace** · *“Replace the yellow armchair with a deep green velvet sofa and hang an abstract painting above it”* |
| <img src="docs/media/examples/relight.jpg" alt="A summer lake cabin turned into a snowy night"><br>**Relight** · *“Make it a snowy winter night, warm light glowing from the cabin windows”* | <img src="docs/media/examples/restyle.jpg" alt="A portrait turned into a watercolor"><br>**Restyle** · *“Turn it into a hand-painted watercolor illustration”* |
| <img src="docs/media/examples/text.jpg" alt="A shop sign changed to KOKON CAFÉ"><br>**Text** · *“Change the gold sign text to ‘KOKON CAFÉ’”* | <img src="docs/media/examples/expand.jpg" alt="A square lighthouse photo expanded to a panorama"><br>**Expand** · 40 % left and right · *“continue the rocky coastline and the turquoise sea”* |

## Install

**1. Download** from the [latest release](https://github.com/GabrieleLozupone/kokon/releases/latest):

- **Windows:** `Kokon_<version>_x64-setup.exe`. Run it. It installs for your user only, so you don't need
  administrator rights.
- **Mac (Apple Silicon, beta):** `Kokon_<version>_aarch64.dmg`. Open it and drag Kokon to
  Applications. The first time, macOS blocks it because the app is not notarized by Apple:
  open System Settings → Privacy & Security and click **Open Anyway**
  ([details](#macos-says-kokon-cannot-be-opened)).

**2. Set up models.** On first launch Kokon shows your graphics card (or your Mac's chip and
memory), recommends a preset and downloads everything it needs. The download resumes if it is
interrupted and every file is checked against its SHA-256 checksum. On a fast connection the
whole thing takes a few minutes, and the setup screen shows what Kokon can do while you wait.

**3. Edit.** Drop or paste a photo, describe the change and press <kbd>Enter</kbd>.

### Requirements

**Windows**

| | Minimum | Recommended |
| --- | --- | --- |
| **OS** | Windows 10 64-bit | Windows 11 |
| **GPU** | NVIDIA, 12 GB VRAM (RTX 3060 12 GB, 4070) · AMD / Intel 12 GB+ through Vulkan (beta) | NVIDIA, 16 GB+ VRAM (RTX 4080, 5070 Ti, 5080, 4090, 5090) |
| **RAM** | 16 GB | 32 GB |
| **Disk** | 15 GB free | 25 GB free on an SSD |
| **Time per image** <!-- RTX 5070 edit time not measured yet (text to image only, 10-11) --> | RTX 5070 12 GB: ~12 s per 1 MP image, ~42 s at native 2K (text to image) | RTX 5070 Ti 16 GB: ~24 s per edit at Balanced (1.5K), ~36 s for a new image at native 2K |

**Mac (beta)**

| | Minimum | Recommended |
| --- | --- | --- |
| **Chip** | Apple M1 or