Skip to content

armgit / kokon

Public Imported from GitHub
0

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.

docs: AGENTS.md, the entry point for people and coding agents

Gabriele Lozuponeae194c5fb62f
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..4c628ac
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,102 @@
+# 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](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](https://github.com/GabrieleLozupone/kokon/discussions/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.rs` is the only file that knows sd-server's request format;
+ `catalog.rs` pins every download (URL, size, SHA-256); `planner.rs` decides sizes and memory.
+- `crates/qls-service`: thin HTTP service. `src-tauri/`: thin desktop shell. `src/`: React UI, logic in
+ `src/lib/logic.ts`. `mcp/`: MCP server (TypeScript, official SDK).
+- Engine: Kokon's build of stable-diffusion.cpp from the fork `GabrieleLozupone/stable-diffusion.cpp`
+ (branch `kokon`); `engine.json` on 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](docs/engineering-notes.md).
+
+## Build and test
+
+Setup, prerequisites and the full commands are in [CONTRIBUTING.md](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](docs/linux.md) | `bash scripts/build-release-linux.sh` |
+
+Tests, before every commit that touches code:
+
+```bash
+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` (or `src/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](CLA.md).
+
+## Where the docs live
+
+| Doc | What |
+|---|---|
+| [README.md](README.md) | the product for users: install, requirements, FAQ, short roadmap |
+| [docs/STATUS.md](docs/STATUS.md) | **what is in progress, next, known issues, help wanted** |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | build, tests, code style, licences |
+| [docs/engineering-notes.md](docs/engineering-notes.md) | architecture, module map, verified backend facts, engine updates |
+| [docs/platforms.md](docs/platforms.md), [docs/linux.md](docs/linux.md) | per-platform notes; Linux plan and the 0.11 server design |
+| [docs/releasing.md](docs/releasing.md) | publishing a version (maintainer) |
+| [docs/prompting.md](docs/prompting.md), [docs/showcase-prompts.md](docs/showcase-prompts.md) | prompt guide and examples |
+| [marketing/](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:
+
+1. 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.
+2. Add new known issues or help-wanted items with their issue link; remove the ones that are closed.
+3. 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.
+4. 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).
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..43c994c
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d666648..0168269 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -4,6 +4,8 @@ Thanks for helping. Bug reports, docs fixes, example prompts and pull requests a
Kokon is a small project maintained by one person, so short, focused changes are the easiest to
review.
+Using a coding agent? Start from [AGENTS.md](AGENTS.md) and [docs/STATUS.md](docs/STATUS.md).
+
## Before you start
- **Bugs and install problems:** open an issue with the template. The **Settings → Diagnostics →
@@ -31,6 +33,16 @@ bash scripts/dev/mac-dev.sh # build and run the app in development
bash scripts/build-release-mac.sh # Kokon.app + .dmg in dist-release/
```
+**Linux (x86_64, built on Ubuntu 22.04 or WSL):** Rust from rustup (Ubuntu's `cargo` package is too
+old) and Node 22+. Clone on the Linux disk, not under `/mnt/c`.
+
+```bash
+bash scripts/build-release-linux.sh --setup # once: system packages
+bash scripts/build-release-linux.sh # .deb + .rpm in dist-release/
+```
+
+A quick run without packaging and the details are in [docs/linux.md](docs/linux.md).
+
To generate images you need the models. The app's first-run setup screen downloads them, or you
can point it at an existing stable-diffusion.cpp folder. Most code changes (planner, geometry,
UI logic, MCP) can be tested without a GPU through the unit tests.
diff --git a/scripts/dev/agent-context.mjs b/scripts/dev/agent-context.mjs
new file mode 100644
index 0000000..c7bc7ff
--- /dev/null
+++ b/scripts/dev/agent-context.mjs
@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+// Prints Kokon's status pages for a coding agent at the start of a session.
+// Claude Code: add it as a SessionStart hook in .claude/settings.local.json, e.g.
+// {"hooks": {"SessionStart": [{"hooks": [{"type": "command", "command": "node scripts/dev/agent-context.mjs"}]}]}}
+// Usage: node scripts/dev/agent-context.mjs [path to the kokon clone] (default: this script's repo)
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = resolve(process.argv[2] ?? join(dirname(fileURLToPath(import.meta.url)), "..", ".."));
+
+function show(title, file, pick) {
+ const path = join(root, file);
+ if (!existsSync(path)) return;
+ const text = readFileSync(path, "utf8");
+ console.log(`===== ${title} (${path}) =====\n${(pick ? pick(text) : text).trim()}\n`);
+}
+
+// Only the "## Rules" section of the maintainer entry point: the rest is read on demand.
+function rulesSection(text) {
+ const start = text.indexOf("## Rules");
+ if (start < 0) return text;
+ const end = text.indexOf("\n## ", start + 1);
+ return text.slice(start, end < 0 ? undefined : end);
+}
+
+console.log(`Kokon repo: ${root}. Read AGENTS.md there before working on Kokon.\n`);
+show("Kokon public status", "docs/STATUS.md");
+show("Maintainer rules", "private/AGENTS.md", rulesSection);
+show("Maintainer status", "private/STATUS.md");