Edit photos by describing the change, on your own GPU. A free, open-source alternative to Nano Banana and ChatGPT image editing: photos stay on your computer, no daily limit. One installer for Windows, Mac and Linux sets up the best open model (Qwen-Image 2.1). MCP server for AI agents.
AGENTS.md
The entry point for anyone working on Kokon: people and coding agents (Claude Code, Codex, Cursor and others). Read this first, then docs/STATUS.md for what is in progress.
What Kokon is
Kokon is the simplest local photo editor: edit photos by describing the change. One installer sets up an open image model on the user's own GPU (Windows, macOS, Linux), and the user brushes an area (or not) and types what they want.
- We pick the best open model, the user picks nothing. Today that is Qwen-Image 2.1 Turbo (8 steps, CFG 1) with three quality presets. No settings to tune: sizes, memory and presets are decided by the code.
- Expert controls are opt-in only, in Settings, off by default, never next to the prompt box.
- A request fits if it helps someone who has never used ComfyUI. Power-user options go to the bottom of the list.
- Changing the default model needs a model that beats the current one overall on text-to-image, edit, multi-image edit and memory use, on the same test set; the old model stays selectable, with a rollback. Proposals: Discussion #35.
Architecture in one minute
Kokon app (Tauri 2 + React, src-tauri/ + src/) kokon-mcp (mcp/, stdio) scripts
└──── loopback HTTP + token ────┬────────────────────────┘
▼
kokon-service (crates/qls-service): stable API on 127.0.0.1, job queue, gallery
all logic in crates/qls-core (planner, pipeline, imaging, catalog…)
│ /sdcpp/v1/*
▼
sd-server (stable-diffusion.cpp, Kokon's own build) on 127.0.0.1
crates/qls-core: all the logic.sdcpp.rsis the only file that knows sd-server's request format;catalog.rspins every download (URL, size, SHA-256);planner.rsdecides sizes and memory.crates/qls-service: thin HTTP service.src-tauri/: thin desktop shell.src/: React UI, logic insrc/lib/logic.ts.mcp/: MCP server (TypeScript, official SDK).- Engine: Kokon's build of stable-diffusion.cpp from the fork
GabrieleLozupone/stable-diffusion.cpp(branchkokon);engine.jsonon master ships engine updates without an app release. site/: kokon.app (static, deploys on push to master).marketing/: Remotion videos, showcase images, release notes.
Module map and the measured facts behind each default: docs/engineering-notes.md.
Working on the Mac engine (engine-mac/): read engine-mac/AGENTS.md first: optimize for
your own Mac without changing other chips, how to measure, and the report every engine PR carries.
Build and test
Setup, prerequisites and the full commands are in CONTRIBUTING.md. In short:
| Run in development | Release build | |
|---|---|---|
| Windows | npm install, npx tauri dev |
scripts\build-release.ps1 |
| macOS (Apple Silicon, 15+) | bash scripts/dev/mac-dev.sh |
bash scripts/build-release-mac.sh |
| Linux (Ubuntu 22.04 / WSL, rustup cargo) | see docs/linux.md | bash scripts/build-release-linux.sh |
Tests, before every commit that touches code:
cargo test -p qls-core
npm test # UI logic (vitest)
cd mcp && npm test # MCP server (the protocol test needs a built kokon-service)
Most changes (planner, geometry, UI logic, MCP) are testable without a GPU. Anything that runs the model for minutes (real inference, benchmarks, release builds) is run by the maintainer: hand over the exact command.
Conventions
- Logic in
qls-core(orsrc/lib/logic.ts), where it can be unit-tested; service, shell and MCP stay thin. - Measured defaults carry their source. If you change a size, memory budget or backend flag, say in the comment what you measured it on (GPU, OS, bench). Comments explain why.
- Add or update a test for behaviour you change. Tests never touch real user folders.
- UI text and docs: plain, short English. Follow the style of the file you edit (
cargo fmt, strict TypeScript). - Methods must generalize: no constants tuned on one image; every step falls back safely when it doesn't apply.
- Don't commit model files or large binaries. Code is AGPL-3.0-only; contributors sign the CLA.
Where the docs live
| Doc | What |
|---|---|
| README.md | the product for users: install, requirements, FAQ, short roadmap |
| docs/STATUS.md | what is in progress, next, known issues, help wanted |
| CONTRIBUTING.md | build, tests, code style, licences |
| docs/engineering-notes.md | architecture, module map, verified backend facts, engine updates |
| docs/platforms.md, docs/linux.md | per-platform notes; Linux plan and the 0.11 server design |
| docs/releasing.md | publishing a version (maintainer) |
| docs/prompting.md, docs/showcase-prompts.md | prompt guide and examples |
| marketing/ | videos, showcase images, release notes per version |
Keeping docs/STATUS.md current
At the end of every task that changes what users get or what is planned:
- Move what you finished from "In progress" to "Recently shipped" (or "Done on master, not released yet"), with the PR or issue link, and change the "Updated" date at the top.
- Add new known issues or help-wanted items with their issue link; remove the ones that are closed.
- Check the items against GitHub (
gh issue list,gh pr list, releases) rather than memory: STATUS must never claim something the repo doesn't show. - Keep the README roadmap short and in step with it.
node scripts/dev/agent-context.mjs prints the STATUS pages; agents can run it at session start (Claude Code:
a SessionStart hook in .claude/settings.local.json).
If a private/ folder exists, read private/AGENTS.md next (maintainer only).