A small image tool for your Mac. View an image in a Kitty-compatible terminal, then open a lightweight editor when you need to change it.
candy photo.png
candy edit photo.pngCandy uses a native Swift/AppKit editor and a shared Rust image engine, with macOS Image I/O and Apple Vision. Requires macOS 14+. Release binaries support Apple Silicon.
Install the app and CLI together with Homebrew:
brew install --cask rath/tap/candyOr download the ZIP from GitHub Releases,
unzip it, and drag Candy.app to Applications. Release apps are signed with
Developer ID and notarized by Apple. Rust and Xcode are not needed to run them.
The Homebrew installation also puts candy on your PATH.
To update, quit Candy and run brew update && brew upgrade --cask candy.
Install Rust 1.95 or newer and Xcode 16 or newer (Swift 6), then build the application and CLI together from this repository:
scripts/build-app.sh
./target/release/candy edit photo.pngInstall just the CLI into Cargo's bin directory (make sure it is on your PATH):
cargo install --locked --path crates/candycargo install does not build the Swift editor. Build dist/Candy.app with the
script above and open it, or copy it to /Applications or ~/Applications:
open dist/Candy.appThe bundle includes a CLI at Contents/Helpers/candy. The GUI executable is
Contents/MacOS/Candy; they are in separate directories for case-insensitive
macOS filesystems. The CLI uses CANDY_APP when set, otherwise a bundle beside
or containing the executable, a repository dist/Candy.app, or the app
registered with LaunchServices. An invalid CANDY_APP is reported explicitly.
CANDY_APP=/path/to/Candy.app candy edit photo.pngThe script builds for the current architecture; --debug selects a debug build.
The bundle is ad-hoc signed for local use, not Developer ID signed or notarized.
Each build stages a clean bundle before replacing dist/Candy.app.
Open images from the File menu, drag and drop, Finder Open With, or the CLI.
The bundle declares supported document types without changing your default
image application.
candy photo.png probes Kitty graphics support and displays a fitted preview
when available. Otherwise it launches the editor. candy edit photo.png
launches a detached editor and returns control to the shell immediately.
Running candy without arguments in an interactive terminal opens an empty editor.
Pipe or redirect an image into Candy to display it without naming a file. -
explicitly selects stdin; an explicit file path takes precedence over piped input.
cat photo.png | candy
candy < photo.heic
cat drawing.svg | candy -
cat photo.jpg | candy --display guiCandy reads one image through EOF and detects its format from the contents,
including SVG and SVGZ. Empty or invalid input is an error. Relative resources
in a piped SVG resolve against the current directory. Stdin is supported for
display only; edit, inspect and CLI editing commands still take file paths.
Use ./- to display a file literally named -.
The same automatic GUI fallback applies to stdin. The editor opens it as
stdin.png; first Save asks for a destination, and closing before making edits
does not ask to save. A private cache file carries the full-resolution image to
the editor and is removed after loading.
candy --display gui photo.heic
candy --display kitty photo.avifInside tmux, previews travel through tmux passthrough, which needs
set -g allow-passthrough on or all, and are placed with Kitty Unicode
placeholders so tmux scrolls and redraws them like text. There, automatic
detection asks tmux instead of probing the terminal: it displays inline when
passthrough is enabled and tmux reports a Ghostty or kitty client, and launches
the editor otherwise. --display kitty skips capability detection. GNU screen
passthrough and the iTerm image protocol are not implemented. Redirected
image-display output is rejected rather than writing escape sequences into a
file. Automatic detection has been checked in Ghostty, both directly and inside
tmux.
In local tmux sessions, Candy hands the preview to the terminal in a private
temporary PNG file using Kitty's temporary-file transport. This avoids chunked
image uploads colliding with graphics from another pane, such as a video player.
The terminal deletes the file after reading it. Candy waits up to two seconds
for that deletion; failed or timed-out transfers are cleaned up and reported as
errors. Sessions with SSH_CONNECTION, SSH_CLIENT or SSH_TTY set keep the
inline data transport, since the terminal cannot read files on the remote host;
concurrent graphics uploads can still collide there.
With allow-passthrough on, tmux drops passthrough data that arrives while it
has a redraw pending. That happens when another pane in the same window
scrolls by inserting or deleting lines while a preview uploads. Local file
transfers report a timeout; inline data transfers can leave a blank preview
without an error, because terminal replies reach Candy through tmux as keystrokes.
set -g allow-passthrough all forwards image data even while a redraw is
pending, but it also lets panes in hidden windows write to the terminal.
- Select: drag a rectangle, move it or resize its corners, then extract it into a new tab.
- Mosaic: pixelate the selected rectangle with an adjustable block size.
- Highlight: draw translucent strokes with adjustable color, size and opacity.
- Text mosaic: detect text locally with Apple Vision, review or adjust boxes, then apply mosaic to the selected box or to all boxes. Applying to one box keeps the others available for review. Cancel or press Escape to clear the remaining boxes without changing the image. Detection is script-independent; English, Korean and Japanese text are checked.
- Resize: set dimensions, optionally preserving the aspect ratio, or rotate by 90° in either direction.
- Flatten alpha: composite transparency onto a chosen solid color.
- Eyedropper: read a pixel's color. A loupe beside the pointer magnifies the
surrounding 11 × 11 pixels and shows the center pixel as hex (
#faac30) and decimal (250, 172, 48). Click to pin a pixel, then use the arrow keys to move the pin one pixel at a time, or ten with Shift. Click the hex or RGB value above the canvas to copy it; Cmd+C copies the hex value. Values are the 8-bit sRGB pixels Candy edits and exports, read at full resolution; a pixel that is not opaque adds its alpha (#faac3080,250, 172, 48, 128).
File, Edit, View and Tools actions live in the macOS menu bar. Each document has a native window, toolbar, contextual controls, canvas, and undo/redo. Native tabs follow your macOS preference; use Window → Merge All Windows or Move Tab to New Window to group or separate documents. The interface follows your macOS language: English, or Korean or Japanese when macOS prefers one of them. Detailed error messages from the image engine stay in English. First Save asks for a new file; subsequent saves update that copy. Save As creates another copy. The save panel has a Format selector for PNG, JPEG, HEIC, WebP, AVIF (where macOS can encode it), TIFF, GIF, BMP, JPEG 2000 and TGA. JPEG, HEIC, AVIF and JPEG 2000 offer a quality slider and numeric input from 1–100. WebP offers lossless or lossy compression, with quality controls in lossy mode. Each document remembers its settings by format after a successful save, including for Save As; new documents start with the defaults. Original input paths, including symlink and hardlink aliases, are protected. Files are encoded before an atomic replacement, and closing unsaved documents prompts to save or discard.
| Shortcut | Action |
|---|---|
| Cmd+O | Open image |
| Cmd+S / Shift+Cmd+S | Save / Save as |
| Cmd+Z / Shift+Cmd+Z | Undo / Redo |
| Cmd+W / Cmd+Q | Close document / Quit |
| Cmd+0 / Cmd+9 | Actual size / Zoom to fit |
| Cmd+1 … Cmd+7 | Select, Mosaic, Highlight, Text mosaic, Resize, Flatten alpha, Eyedropper |
| Cmd+C | Copy the eyedropper color as hex |
| Arrow keys / Shift+arrow keys | Move the eyedropper pin by 1 / 10 pixels |
| Escape | Cancel a drag, clear text boxes, clear the eyedropper pin, or clear selection |
| Delete / Backspace | Remove the selected OCR box |
| Space + drag | Pan |
| Scroll / pinch | Zoom |
Actual Size maps one image pixel to one display backing pixel (so a 1000 px image occupies 500 logical points on a 2× Retina display). Fit never enlarges images beyond that size; manual zoom ranges from 1% to 1600%. A new window sizes itself to show its first image at Actual Size, or as large as the screen allows.
OCR boxes are locked while detection runs. Other tools remain available; editing the image discards the old detection result. During quit confirmation all documents are locked; cancellation restores interaction and opens queued files.
Text detection finds candidate bounds without transcribing the words. It uses Vision's text-region detector with full-resolution pixels supplied directly, avoiding PNG conversion and OCR language-model startup even on images without text. It can miss text or mistake graphics for text. Review the detected regions before sharing an edited image; mosaic is a visual effect, not a guarantee of irreversible redaction.
Editing commands write to an output path (-o), whose extension selects the
format, or replace the input itself with -i/--in-place. Rectangle
coordinates are x,y,width,height in image pixels, measured from the top-left
after EXIF rotation.
candy resize photo.heic --width 1200 -o smaller.png
candy resize scan.tif --width 800 --height 600 -o exact.webp
candy rotate photo.heic --cw -o upright.heic
candy rotate photo.jpg --ccw -i
candy crop photo.png --rect 20,30,300,200 -o crop.heic
candy mosaic photo.png --rect 20,30,300,200 --block-size 16 -o mosaic.png
candy mosaic screenshot.png --text -o text-mosaic.png
candy flatten logo.png --background '#ffffff' -o flat.jpg
candy resize photo.png --width 1200 -o photo.jpg --quality 80
candy resize photo.png --width 1200 -o photo.webp --webp-mode lossy --quality 80
candy rotate photo.heic --cw -o rotated.heic --quality 90One resize dimension preserves the aspect ratio; providing both sets the exact
size. rotate turns a quarter turn clockwise (--cw) or counterclockwise
(--ccw). Use --force to replace an existing output; it never permits overwriting
the input. --in-place is the one way to change the input: the result is
re-encoded in the file's own format and swapped in atomically, keeping the
file's permissions and following a symlink to the file it points at. Metadata
such as EXIF is not carried over, and lossy formats are recompressed, so prefer
-o when the original matters. Run candy --help or candy <command> --help
for details.
All CLI editing commands accept --quality <1–100> for JPEG, lossy WebP,
HEIC, AVIF and JPEG 2000. WebP defaults to lossless; select
--webp-mode lossy to use quality (80 when omitted), or --webp-mode lossless
to explicitly request lossless output. Quality with lossless WebP, quality on
other formats, and WebP mode on a different format are errors. A quality of 100
does not select WebP lossless compression.
HEIC and AVIF quality 100 map to Image I/O quality 0.999 to avoid native
encoder failures at exactly 1.0 on some macOS versions and hardware.
candy inspect photo.heic reads the stored format, dimensions, EXIF
orientation, color model, bit depth, alpha, color profile and DPI from the
file's headers, then reports statistics of the pixels Candy would edit (8-bit
sRGB after orientation): opaque, translucent and transparent counts, the
alpha-weighted average color and the number of distinct colors. --json
prints the same report as one JSON object; pixels is null and
pixels_error explains why when the image cannot be decoded.
| Operation | Formats |
|---|---|
| Open | Anything Image I/O on your Mac decodes: PNG, JPEG, WebP, HEIC/HEIF, AVIF, GIF, TIFF, BMP, JPEG 2000, PSD, TGA, ICO, ICNS, OpenEXR, Radiance HDR, PBM, camera RAW and DNG, and JPEG XL on macOS 26 or later; plus SVG and SVGZ, rasterized by resvg |
| Save | PNG, JPEG (default quality 92), WebP (default lossless; lossy default quality 80), HEIC, AVIF and JPEG 2000 (default quality 85), TIFF (LZW), GIF (256 colors), BMP, TGA |
Images are edited as 8-bit sRGB RGBA. EXIF orientation is applied on load; source metadata, HDR data and wide-gamut profiles are not retained on export. JPEG exports flatten transparency onto white; GIF keeps pixels at or above 50% alpha and drops the rest. AVIF saving needs an Image I/O with an AVIF encoder, which arrived after macOS 14 (verified on macOS 26); older systems explain this when asked. RAW files are developed with Image I/O's defaults. Only the first image/frame is loaded. Images are limited to approximately 64 megapixels. The GUI preview is limited to 4096 pixels per side; edits and saves use full image resolution. Encoded files and stdin are limited to 512 MiB. SVG/SVGZ input and the total decoded XML of the document and its referenced or embedded SVGs are limited to 32 MiB; excessive input is rejected before decoding or saving. Lossy WebP additionally limits each side to 16,383 pixels. Its encoder is included in the app and CLI; no external encoder installation is needed.
SVG files are rendered with the bundled resvg at their own size, enlarged so
the longer side is at least 1024 pixels and reduced to fit the pixel limit, with
transparency preserved. Text uses the fonts installed on your Mac. Nested SVG
<image> references resolve against the file's directory; embedded or linked
raster images (PNG, JPEG, GIF, WebP) inside an SVG are skipped to keep the
binaries small. candy inspect reports the rendered size. Edited SVGs save in a
raster format; Candy does not write SVG.
This version has no layers, animation editing, cloud services or LLM integration. Text detection runs locally and sends no image data to a service. Detection quality and codec availability depend on the installed macOS version.
cargo fmt --all --check
cargo clippy --locked --workspace --all-targets -- -D warnings
cargo test --locked --workspace
scripts/build-app.sh --debug
scripts/swift.sh test
scripts/build-app.shcandy-core: pixel operations, edit history and atomic export.candy-macos: shared Image I/O decoding and Apple Vision text detection.candy-ffi: synchronous C ABI, owned document/image handles, bounded previews.candy: Rust CLI, Kitty graphics protocol and native-app launcher.macos: SwiftPM AppKit application, document coordination and canvas interaction.
New edits apply to the current pixels. Undo/redo reuse up to 16 rendered checkpoints within a 64 MiB budget per document, in addition to the original and current image; evicted states are reconstructed from the nearest earlier checkpoint. Failed edits preserve both pixels and redo history.
The Swift target links the Rust engine statically. Build candy-ffi before running
Swift tests alone (cargo build --locked -p candy-ffi). scripts/swift.sh keeps
Swift caches in macos/.build and disables the nested package-manifest sandbox
so it can run inside an existing development sandbox. It fingerprints the Rust
archive to force relinking after Rust-only changes; use the wrapper for builds
and tests. Native OCR and UI checks need normal macOS access to Vision/pixel
buffers and the window server.
Interface text uses the English text as its key (localized(_:) in CandyKit).
Korean and Japanese translations live in macos/Resources/ko.lproj/ and
macos/Resources/ja.lproj/Localizable.strings; a Swift test fails when an entry
is missing, unused or has different placeholders, or when scripts/build-app.sh
does not ship a table. To see a translated interface without changing system
settings, pass the language to that process only:
open -n -a dist/Candy.app --args -AppleLanguages '(ko)'
open -n -a dist/Candy.app --args -AppleLanguages '(ja)'Debug builds support a process-only appearance override for visual checks:
CANDY_TEST_APPEARANCE=dark dist/Candy.app/Contents/MacOS/CandyQuit any existing test instance first. This does not change system preferences and is not included in release builds.
Tests cover edit boundaries, alpha compositing, save protection, undo state,
terminal encoding, FFI ownership, native document/async-state regressions, a save-and-reopen
round trip through every export format, PSD/ICO/ICNS/OpenEXR/PBM decoding, SVG
rasterization, EXIF
orientation and Korean/English text-region coverage. Synthetic fixtures can be regenerated with
swift scripts/make-fixtures.swift crates/candy-macos/tests/fixtures.
GitHub Actions runs the checks and produces a zipped local app bundle on macOS.
The application icon is committed as macos/Resources/AppIcon.icns. Its sources
are scripts/icon/app-icon.svg and the simplified 16-point
scripts/icon/app-icon-small.svg. After editing either, regenerate it with
scripts/build-icon.sh (requires rsvg-convert from Homebrew librsvg).
To profile text detection on synthetic blank, graphical, Korean/English and large images (requires normal macOS Vision access):
CANDY_OCR_TIMING=1 cargo run --locked --release -p candy-macos --example ocr-timingThe opt-in log separates image preparation from Vision execution and reports no image contents. Timings depend on the machine and macOS version.
Made by Jang-Ho Hwang. MIT licensed. See PRODUCT.md for scope and DESIGN.md for the editor's visual conventions.
Maintainers: see releasing for signing, notarization, GitHub Releases, and Homebrew distribution.
The GitHub Pages landing page in English, Korean and Japanese is in site/. See website maintenance for preview, publishing, and DNS setup.