Stencil
<p align="center" <a href="https://andrew1407.github.io/stencil/"<img src="browser/favicon.svg" alt="Stencil logo" width="120" height="120"</a </p
An image annotation / drawing tool: load an image, draw polylines and rectangles over it, edit points numerically, convert pixel coordinates to page (cm) coordinates with optional f(x,y) formula transforms, and save your work.
Stencil ships as one shared logic core with a family of front-ends and services:
| App | Path | Stack | Docs | Use cases | |---|---|---|---|---| | Core | core/ | C++17, STL-only, GUI-free shared library | core/README.md | — | | Browser | browser/ | Vanilla ES-module JS, no build step (optional single-file bundle) | browser/README.md | browser | | Desktop | desktop/ | C++17 + Qt 6, CMake build | desktop/README.md | desktop | | CLI | cli/ | Zig, wraps the C++ core | cli/README.md | cli | | Python | pystencil/ | Stdlib-only Python, drives the C++ core via ctypes | pystencil/README.md | — | | MCP server | mcp/ | Rust, exposes the CLI's pipeline as MCP tools | mcp/README.md | — | | Collaboration server | server/ | Go, stores/shares projects + live multi-client edit sessions | server/README.md | — | | Telegram bot | bot/ | .NET (C#), chat-driven editing over the CLI + server REST | bot/README.md | bot |
A companion Chrome extension (browser-extension/) feeds the browser editor: it lists, searches and filters every image on any web page and opens a chosen image in the Stencil editor, with a quick in-page crop. A VS Code extension (vscode-extension/) gives .stc scripts (below) highlighting, squiggles, completions, hovers and a Run button, and gives a saved .stencil project its own icon. The cross-surface smoke harness lives in e2e/.
What each app looks like, scenario by scenario with screenshots and clips, is in usecases/ — one USECASES.md per app, including the extension and the VS Code extension; the images are regenerated by usecases/capture-runner/, never edited by hand.
Every surface also carries an AI assistant — describe an edit in words and a model you point Stencil at plans it. Setup guide: AI assistant — setting up a model. Edits you want to repeat go in a .stc script instead: Scripts (.stc).
How the pieces fit together — the shared core, the parity contract, the layer model per app — is in ARCHITECTURE.md.
Development
No dependencies to install anywhere: each subproject runs on its platform's built-in tooling (the desktop needs Qt 6; the C++ tests use a single Doctest header fetched at configure time; the CLI shells out to a system ffmpeg for video input only).
| Subproject | Guide | Covers | |---|---|---| | Core | core/README.md | build & test the shared library | | Browser | browser/README.md | serve & test the app, the optional single-file build | | Desktop | desktop/README.md | build, test & run the Qt app | | CLI | cli/README.md | build, test & run the Zig tool | | Python | pystencil/README.md | build & test the package | | MCP server | mcp/README.md | build, test & register the server | | Collaboration server | server/README.md | build, test & run the Go server | | Telegram bot | bot/README.md | build, test & run the bot | | Chrome extension | browser-extension/README.md | load unpacked & test | | VS Code extension | vscode-extension/README.md | package the .vsix, install & test | | E2E harness | e2e/README.md | run the cross-surface smoke suite |
Docker. Five subprojects ship a multi-stage Dockerfile. The first four compile core/, so build them from the repo root with -f; the server image builds from its own ./server context:
docker build -f browser/Dockerfile -t stencil-browser . && docker run --rm -p 8080:80 stencil-browser
docker build -f cli/Dockerfile -t stencil-cli . && docker run --rm -v "$PWD:/work" -w /work stencil-cli --help
docker build -f mcp/Dockerfile -t stencil-mcp . && docker run --rm -i -v "$PWD:/work" -w /work stencil-mcp
docker build -f bot/Dockerfile -t stencil-bot . && docker run --rm -e TELEGRAM_BOT_TOKEN=123:abc stencil-bot
docker build -t stencil-server ./serverFor the full local stack — Postgres + Redis + the collaboration server (plus the browser app and an on-demand mcp profile) — the repo-root docker-compose.yml wires it together; it also backs the full-stack e2e/ suite:
docker compose up --build server # collab server on :8090 (REST/WS) + :8091 (TCP), with its db/redisScripts (.stc)
A stencil script is a plain-text file of @ directives that batches the same edits over one image, a folder or a glob — the repeatable counterpart to clicking and to asking the assistant: