If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/flameshot-org/flameshot shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 1d ago
• 22+ active contributors
• Distributed ownership (top contributor 35% of recent commits)
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ GPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live flameshot-org/flameshot repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/flameshot-org/flameshot.

What it runs against: a local clone of flameshot-org/flameshot — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in flameshot-org/flameshot | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of flameshot-org/flameshot. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/flameshot-org/flameshot.git
#   cd flameshot
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of flameshot-org/flameshot and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "flameshot-org/flameshot(\\.git)?\\b" \\
  && ok "origin remote is flameshot-org/flameshot" \\
  || miss "origin remote is not flameshot-org/flameshot (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/flameshot-org/flameshot"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Flameshot is a cross-platform screenshot utility written in C++ with Qt that captures, annotates, and shares screenshots via a graphical editor. It runs on Linux, macOS, and Windows, providing tools for drawing, blurring, adding text, and exporting to clipboard or file with keyboard shortcuts and CLI support. Monolithic C++ application with CMake build system (CMakeLists.txt at root, modular cmake/ config includes for StandardProjectSettings, Sanitizers, StaticAnalyzers). Source likely organized by feature modules (not visible in file list but typical: src/gui, src/cli, src/core). Data files (icons, desktop entry, D-Bus service definitions) in data/ directory. Platform-specific packaging configs (PKGBUILD for Arch, appveyor.yml for Windows CI).

Linux/macOS/Windows power users and system administrators who need fast screenshot capture with in-app annotation, clipboard integration, and scriptable CLI access—particularly those who want escape from heavyweight tools like Greenshot or built-in OS screenshot apps.

Production-ready and actively maintained. The project has stable releases, multi-platform CI/CD via GitHub Actions (.github/workflows/), extensive localization via Weblate, and packaging across snap, flatpak, and native installers. Recent workflows show active builds for Linux ARM, Linux x86, macOS, and Windows.

Low risk overall—mature codebase with 730KB C++ and established build infrastructure. Risks: single organization (flameshot-org) with distributed maintainers; relies on Qt which has occasional breaking changes between major versions; no visible automated test suite in the file list (typical for older GUI projects). Monitor Qt version constraints in CMakeLists.txt.

Active cross-platform build improvements—recent workflows for Linux ARM packaging, macOS, Windows, and CMake build validation. Code quality checks via clang-format and clang-tidy enabled (.clang-format, .clang-tidy in root). Nightly development builds are available. D-Bus integration (data/dbus/org.flameshot.Flameshot.xml) suggests ongoing desktop integration refinement.

git clone https://github.com/flameshot-org/flameshot.git
cd flameshot
mkdir build && cd build
cmake ..
make -j$(nproc)
./flameshot

See CMakeLists.txt for Qt6/Qt5 detection and platform-specific dependencies (likely libxcb on Linux, native frameworks on macOS/Windows).

Daily commands: After build above: ./flameshot starts the GUI with system tray integration. For CLI: ./flameshot screenshot --help (config file at ~/.config/flameshot/flameshot.ini). D-Bus service auto-registers for global hotkey integration.

• CMakeLists.txt: Defines Qt version detection, cross-platform compiler flags, and link against system libraries (X11/Wayland on Linux, native APIs on macOS/Windows)
• .github/workflows/build_cmake.yml: Validates all pull requests via CMake build on multiple platforms; required CI gate
• data/dbus/org.flameshot.Flameshot.xml: D-Bus service contract enabling global hotkey capture on Linux desktop environments
• data/desktopEntry/package/org.flameshot.Flameshot.desktop: Linux desktop integration metadata; controls application icon, name, and startup behavior in DE menus
• .clang-format: Enforces code style consistency across C++ codebase; CI blocks commits that violate this
• cmake/StandardProjectSettings.cmake: Centralizes compiler flags, C++ standard, and platform-specific build rules; source of truth for build configuration

Core GUI code likely in src/gui (not listed but inferred); CLI in src/cli; platform-specific capture in src/core/. To add a new annotation tool: modify GUI widget hierarchy in src/gui/tools/. To add a new export format: modify export handlers (likely src/core/export/). Configuration schema in CMakeLists.txt affects Qt resource files. Always run cmake-format on CMakeLists.txt before commit.

Qt version compatibility: CMakeLists.txt likely conditionally uses Qt5 vs Qt6 APIs; verify your Qt installation matches. X11/Wayland detection on Linux: screenshot capture code requires xdotool or equivalent; build may fail silently on Wayland-only systems. No explicit dependency lock file visible—CMakeLists.txt references external packages that may have breaking updates. D-Bus service requires dbus-daemon running for hotkey support on Linux (fails gracefully but features reduced).

• D-Bus Service Activation — Flameshot's hotkey capture on Linux relies on D-Bus auto-activation (data/dbus/); understanding this is essential for debugging why global hotkeys don't work or app won't start
• Platform-Specific Display Server APIs — Screenshot capture must use native X11 (XGetImage), Wayland (zwlr_screencopy), or Windows/macOS APIs; the codebase conditionally compiles these paths and you'll encounter #ifdef WIN32, #ifdef Q_OS_MAC
• Qt Resource System (QRC) — Icons and images are compiled into the binary via data/graphics.qrc; modifying artwork requires rebuilding and understanding Qt's resource compiler
• Cross-Platform Build Configuration (CMake) — CMakeLists.txt and cmake/ subdirectory use feature detection and conditional linking; understanding generator expressions and target properties is critical for platform-specific changes
• Desktop Entry Specification — org.flameshot.Flameshot.desktop and .metainfo.xml control Linux desktop integration (menus, icons, MIME types); non-compliant entries cause packaging failures
• AppData/MetaInfo for Linux Distributions — data/appdata/org.flameshot.Flameshot.metainfo.xml feeds app store listings and package managers; required for snap/flatpak/distro repos
• Clipboard MIME Type Handling — Flameshot exports screenshots to system clipboard in multiple formats (PNG, JPEG); cross-platform clipboard APIs differ significantly and require Qt's QMimeData abstraction

• maim/maim — Lightweight X11 screenshot utility with similar annotation-free approach; shows alternative architecture for capture-only tools
• ShareX/ShareX — Windows/Mac screenshot and sharing tool with comparable feature set; reference for cross-platform GUI patterns
• naiveproxy/naiveproxy — Not directly related but shows CMake + native platform APIs pattern for cross-platform C++ apps
• Qt/qtbase — The Qt framework itself; essential dependency and source of truth for GUI API and platform integration
• freedesktop/dbus — D-Bus specification and reference implementation; critical for Linux hotkey/service activation integration

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for screenshot capture and annotation modules

The repo has comprehensive CI/CD workflows (Linux-pack.yml, Windows-pack.yml, MacOS-pack.yml) and uses clang-tidy for static analysis, but there's no evidence of unit tests in the file structure. Given Flameshot's core functionality involves capturing screenshots and applying annotations, adding tests for these critical modules would prevent regressions and improve code confidence across platforms.

• [ ] Create tests/unit/ directory structure mirroring src/ layout
• [ ] Add unit tests for screenshot capture logic (platform-specific: Linux/Windows/macOS)
• [ ] Add unit tests for annotation tools (drawing, text, shapes from material icons in data/img/material/)
• [ ] Integrate test execution into build_cmake.yml workflow with coverage reporting
• [ ] Update CMakeLists.txt to enable test builds with optional enable_testing()

Add GitHub Actions workflow for code quality checks on all platforms

The repo has clang-format.yml for formatting checks, but no unified CI workflow that runs clang-tidy, CMake format validation, and compiler warning checks across Linux/Windows/macOS simultaneously. The existing cmake/StaticAnalyzers.cmake and cmake/CompilerWarnings.cmake are set up but not systematically gated in CI.

• [ ] Create .github/workflows/code-quality.yml that runs on PRs
• [ ] Configure clang-tidy analysis step using cmake/StaticAnalyzers.cmake settings
• [ ] Add cmake-format validation step for CMakeLists.txt and cmake/ files against .cmake-format.yaml
• [ ] Add compiler warnings step across GCC/Clang (Linux), MSVC (Windows), and Apple Clang (macOS)
• [ ] Link workflow to prevent merge until all quality gates pass

Create installation and configuration documentation for data files and desktop integration

The data/ directory contains critical desktop integration files (data/desktopEntry/, data/dbus/, data/appdata/) and icon assets (data/img/hicolor/) but these aren't documented. New contributors may not understand how these files are packaged or why icons exist at multiple resolutions, causing packaging mistakes across platforms.

• [ ] Create docs/DESKTOP_INTEGRATION.md explaining DBus service setup (data/dbus/org.flameshot.Flameshot.service.in)
• [ ] Document appdata/metainfo.xml purpose for app store integration (data/appdata/org.flameshot.Flameshot.metainfo.xml)
• [ ] Add icon scaling guide explaining why multiple resolutions exist in data/img/hicolor/ and when each is used
• [ ] Document PKGBUILD and platform-specific packaging (Linux-arm-pack.yml, Windows-pack.yml, MacOS-pack.yml references)
• [ ] Link documentation from README.md and CONTRIBUTING.md (if it exists)

• Add unit tests for screenshot capture paths: src/core/capture/ likely lacks automated test coverage for different display server types (X11 vs Wayland). Create test fixtures in tests/ directory using Qt Test framework.
• Document CLI examples: README.md mentions 'CLI configuration' but file list shows no docs/cli-examples.md. Add concrete examples for screenshot-to-clipboard, batch export, and config override workflows.
• Internationalization completeness check: data/appdata/org.flameshot.Flameshot.metainfo.xml and .desktop file may have untranslated strings. Extract new i18n keys and update po files in i18n/ directory (if it exists).

Flameshot, being a desktop screenshot application, has a relatively good security posture with no critical vulnerabilities identified in the visible codebase structure. However, there are several areas requiring attention: (1) Secure handling of sensitive image data and temporary files, (2) Proper input validation for configuration and image metadata, (3) D-Bus service authorization controls, and (4) Dependency version management. The application should implement strict input validation, secure file handling with proper permissions, D-Bus security policies with PolicyKit integration, and maintain pinned dependency versions. No hardcoded secrets or obvious injection vulnerabilities were detected in the file structure analysis. The presence of security scanning tools in the CI/CD pipeline (.clang-tidy, Sanitizers) suggests good security practices are already in place.

• Medium · Potential Insecure Deserialization in Qt Application — Application-wide (Qt application handling user data). As a Qt-based screenshot application that handles image data and potentially processes configuration files, there is a risk of insecure deserialization if the application loads untrusted configuration or image metadata without proper validation. Fix: Implement strict input validation for all configuration files and image metadata. Use Qt's safe serialization methods and avoid deserializing untrusted data directly.
• Medium · Missing Security Headers in Desktop Application — Desktop application with potential network communication. While this is a desktop application rather than a web service, if any embedded web functionality exists (notifications, help documentation), it may lack proper security headers and Content Security Policy. Fix: If the application communicates with web services or displays web content, ensure proper SSL/TLS certificate validation, CSP headers, and secure communication protocols.
• Low · Potential Information Disclosure via Screenshots — Screenshot capture and storage mechanisms. As a screenshot application, sensitive information in captured images could be inadvertently exposed if clipboard handling or temporary file storage is not properly secured. Fix: Ensure temporary screenshot files are stored securely with restricted permissions, implement secure clipboard clearing, and provide users with warnings about capturing sensitive content.
• Low · No Visible Dependency Pinning in Package Management — CMakeLists.txt and dependency management files. The provided dependency file content is empty. Without explicit dependency version constraints, the build could be vulnerable to supply chain attacks or breaking changes in dependencies. Fix: Implement strict version pinning for all external dependencies. Use CMake's find_package() with specific version constraints and maintain a lock file for reproducible builds.
• Low · D-Bus Service Potential Security Risk — data/dbus/org.flameshot.Flameshot.service.in and related D-Bus XML definitions. The application exposes D-Bus service (org.flameshot.Flameshot.service.in), which could be exploited if the service doesn't properly validate callers or implement authorization checks. Fix: Implement proper D-Bus security policies using PolicyKit for sensitive operations. Restrict D-Bus method calls to authorized users and validate all inputs from D-Bus requests.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.