Cappy

Cappy is a cross-platform screenshot and pinning tool focused on fast startup, low overhead, and clean engineering boundaries.

Current scope:

• Windows 10/11
• Linux X11
• Packaging targets: .exe and .deb

Current implementation focus:

• Linux X11 first
• SunnyCapturer-style shortcut-first capture flow

Out of scope for the first phase:

• Wayland
• macOS
• Cloud or account features

What It Does

Cappy is built around a shortcut-first workflow. The app can stay in tray and let the user complete the common capture flow without opening the main window.

Current user-facing capabilities:

• F1 entry for screenshot capture on Linux X11 and Windows
• follow-window preselection under the cursor, with fallback to manual region selection by dragging again
• region, current-screen, and virtual-desktop capture flows
• capture toolbar for copy, save, pin, OCR, and drawing tools
• pin windows with drag, resize, shadow, lock, flip, rotate, invert, restore, save, copy, and OCR entry
• text, numbering, shapes, arrow, marker, and mosaic annotation tools
• explicit save flow with no default auto-save
• local OCR flow and configurable OCR provider settings
• theme, language, hotkey, save-path, history-limit, auto-start, silent-startup, and close-to-minimize settings

Quick Start

Linux X11

1. Install build dependencies:

sudo apt update
sudo apt install -y \
  build-essential \
  cmake \
  ninja-build \
  pkg-config \
  qt6-base-dev \
  qt6-base-dev-tools \
  libx11-dev \
  libxfixes-dev \
  libxtst-dev \
  libxcb1-dev \
  dpkg-dev \
  fakeroot \
  lintian

2. Build and package:

./scripts/package-linux.sh build-release

3. Install the generated package:

sudo dpkg -i ./cappy_*.deb

4. Launch:

• app menu: Cappy
• terminal: cappy

Windows

1. Install:
   • Visual Studio 2022 with MSVC v143
   • CMake 3.28+
   • Ninja
   • NSIS
   • Qt 6.8.3 msvc2022_64
2. Open a PowerShell or MSVC developer shell.
3. Build and export the installer:

./scripts/package-windows.ps1 -BuildDir build-win -QtBinDir "C:\Qt\6.8.3\msvc2022_64\bin"

4. Install the generated .exe installer from the build output.

For the full deployment process, packaging details, and artifact verification steps, see docs/build-and-package.md.

Principles

• Keep the core fast enough to stay resident in tray with low memory pressure.
• Prefer explicit module boundaries over convenience coupling.
• Treat platform integrations as replaceable adapters.
• Build a plugin system early, but keep the initial plugin surface narrow.

Planned capabilities

• Region / fullscreen / active-window capture
• Explicit copy / pin / save without default auto-save
• Pin window with topmost, scale, opacity, drag, and click-through
• Annotation tools: rectangle, arrow, text, blur/mosaic
• Shortcut-first command surface, then global hotkeys
• Multi-screen and HiDPI support
• Tray, settings, history, undo/redo

Repository layout

• docs/build-and-package.md: build, dependency, packaging, and distribution baseline
• docs/ci.md: current GitHub Actions baseline and artifact expectations
• docs/architecture.md: module boundaries and plugin model
• docs/roadmap.md: staged delivery plan
• docs/adr/0001-qt6-widgets-plugin-architecture.md: first architectural decision record

Export packages

• Linux .deb: run ./scripts/package-linux.sh build-release
• Windows .exe on a Windows machine: run ./scripts/package-windows.ps1 -BuildDir build-win -QtBinDir "C:\Qt\6.8.3\msvc2022_64\bin"
• Download latest green Windows artifact from GitHub Actions: ./scripts/download-latest-windows-artifact.sh with GH_TOKEN configured

Toolchain baseline

• C++20
• Qt 6.4+ Widgets
• CMake 3.28+
• MSVC 2022 or MinGW-w64 on Windows
• GCC 13+ or Clang 17+ on Linux