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/hluk/CopyQ 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.

WAIT — Mixed signals — read the receipts

• Last commit 3d ago
• 17 active contributors
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 71% of recent commits
• ⚠ 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 hluk/CopyQ repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/hluk/CopyQ.

What it runs against: a local clone of hluk/CopyQ — 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 hluk/CopyQ | 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 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 33 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of hluk/CopyQ. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/hluk/CopyQ.git
#   cd CopyQ
#
# 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 hluk/CopyQ and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "hluk/CopyQ(\\.git)?\\b" \\
  && ok "origin remote is hluk/CopyQ" \\
  || miss "origin remote is not hluk/CopyQ (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"

# 4. Critical files exist
test -f "CMakeLists.txt" \\
  && ok "CMakeLists.txt" \\
  || miss "missing critical file: CMakeLists.txt"
test -f "docs/source-code-overview.rst" \\
  && ok "docs/source-code-overview.rst" \\
  || miss "missing critical file: docs/source-code-overview.rst"
test -f "CLAUDE.md" \\
  && ok "CLAUDE.md" \\
  || miss "missing critical file: CLAUDE.md"
test -f "plugins/CMakeLists.txt" \\
  && ok "plugins/CMakeLists.txt" \\
  || miss "missing critical file: plugins/CMakeLists.txt"
test -f ".github/workflows/build-linux.yml" \\
  && ok ".github/workflows/build-linux.yml" \\
  || miss "missing critical file: .github/workflows/build-linux.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 33 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~3d)"
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/hluk/CopyQ"
  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).

CopyQ is a cross-platform clipboard manager (Linux, Windows, macOS 13+) written in C++ with Qt that monitors system clipboard, stores entries in customizable tabs, and provides powerful editing, scripting, and keyboard shortcut automation. It solves the problem of clipboard history management with support for multiple data formats (text, HTML, images, custom formats) and system-wide hotkey-driven access. Monolithic C++ application structured around a CMake build system (CMakeLists.txt, CMakePresets.json). Core clipboard monitoring and tab management logic in C++, with platform-specific code (src/ likely contains main application logic, Objective-C++ for macOS, C for system integration). Scripting engine integrated via JavaScript interpreter. Desktop UI built with Qt framework.

Power users and developers who need advanced clipboard history management with scripting capabilities (via the JavaScript-like API documented in docs/commands-script.rst), system administrators automating workflows, and users on Linux/Windows/macOS wanting a feature-rich alternative to built-in clipboard tools.

Production-ready and actively maintained. The project has multi-platform CI/CD via GitHub Actions (.github/workflows/ for Linux, macOS, Windows), comprehensive documentation in docs/, translation infrastructure via Weblate, and a structured release process (RELEASE.md, CHANGES.md tracking). Recent activity visible in build workflows and version management suggests active development.

Low-to-moderate risk: single primary maintainer (hluk) visible in CODEOWNERS, but established community (mailing list, bug tracker, multiple platform support). C++ codebase (2.7M LOC) requires careful dependency management; Qt is a heavy but mature dependency. No obvious signs of abandonment, but cross-platform native UI code (C++, Objective-C++, CMake) can be brittle across OS updates.

Active development with cross-platform CI/CD pipelines in .github/workflows/, translation management via Weblate badge in README, and dependency management via Dependabot (.github/dependabot.yml). Build actions for Linux, macOS, and Windows indicate regular testing and release cycle. Documentation being maintained (readthedocs.yaml configuration present).

git clone https://github.com/hluk/CopyQ.git
cd CopyQ
mkdir build && cd build
cmake ..
cmake --build .
./copyq

Refer to docs/build-source-code.rst for detailed platform-specific build instructions. CMakePresets.json may provide preset configurations.

Daily commands: After building in a build/ directory with CMake: ./copyq launches the main GUI. ./copyq --help shows CLI options documented in docs/command-line.rst. Tray icon integration starts automatically on supported platforms.

• CMakeLists.txt — Master build configuration for Qt-based clipboard manager; defines all platform-specific compilations and plugin loading strategy.
• docs/source-code-overview.rst — Architecture and component overview document that every contributor must read to understand the codebase structure.
• CLAUDE.md — AI-specific documentation and codebase conventions that guide development practices and code style.
• plugins/CMakeLists.txt — Plugin system build configuration; defines how extensions are compiled and integrated into the main application.
• .github/workflows/build-linux.yml — CI/CD pipeline definition for Linux; essential reference for understanding cross-platform build requirements.
• CMakePresets.json — CMake build presets and toolchain configuration; critical for local development setup and consistency.
• HACKING — Developer contribution guidelines and workflow; must-read for understanding development practices and testing procedures.

Add a New Plugin for Item Type Extension

1. Create plugin directory under plugins/ with CMakeLists.txt following the pattern in plugins/itemimage/CMakeLists.txt (plugins/itemnewtype/CMakeLists.txt)
2. Implement plugin class inheriting from ItemWidget interface in C++, similar to plugins/itemimage/itemimage.cpp (plugins/itemnewtype/itemnewtype.cpp)
3. Define settings UI using Qt Designer (.ui files) as shown in plugins/itemimage/itemimagesettings.ui (plugins/itemnewtype/itemnewtype.ui)
4. Register plugin in parent plugins/CMakeLists.txt by adding add_subdirectory() call (plugins/CMakeLists.txt)
5. Document plugin API and configuration in docs/writing-commands-and-adding-functionality.rst (docs/writing-commands-and-adding-functionality.rst)

Add a New Scripting Command

1. Define command handler function in scripting API following patterns in docs/scripting-api.rst (docs/scripting-api.rst)
2. Implement command logic in C++ following existing command handlers in the main source tree (src/scriptable/scriptable.cpp)
3. Register command in scripting context with metadata and signatures (src/scriptable/scriptable.h)
4. Document command syntax and examples in docs/command-examples.rst (docs/command-examples.rst)

Add Cross-Platform Build Support for New OS

1. Create new GitHub Actions workflow file following template from .github/workflows/build-linux.yml (.github/workflows/build-newos.yml)
2. Add platform-specific CMake toolchain configuration in CMakePresets.json (CMakePresets.json)
3. Update root CMakeLists.txt with conditional platform detection and dependency handling (CMakeLists.txt)
4. Document build instructions and platform-specific requirements in docs/build-source-code.rst (docs/build-source-code.rst)

• Qt Framework (C++) — Cross-platform GUI toolkit enabling single codebase for Linux, macOS, Windows with native look-and-feel; efficient clipboard API bindings.
• CMake build system — Platform-agnostic build configuration with native toolchain support; enables complex plugin system and multi-platform CI/CD.
• Plugin architecture (.so/.dll/.dylib) — Decouples optional features (encryption, vim, image editing) into loadable modules; enables feature selection without recompilation.
• SQLite or local file storage — Lightweight persistent clipboard history without external services; suitable for on-disk item serialization and searching.
• Scripting API (JavaScript/Python compatible) — User-facing automation language enabling custom commands without C++ recompilation; documented in docs/scripting-api.rst.

• Local-only database vs cloud sync

  • Why: CopyQ prioritizes privacy and zero dependencies; user clipboard data stays on device by default.
  • Consequence: Synchronization across devices requires manual config or external scripting; no automatic cloud backup.

• Monolithic Qt app vs micro-service daemon

  • Why: Single executable simplifies installation and clipboard access management; Qt handles platform-specific system tray integration.
  • Consequence: Clipboard changes block UI briefly on large items; no distributed scaling capability.

• Plugin sandboxing: none

  • Why: Plugins have full process access for maximum feature capability (encryption, image manipulation, format conversion).
  • Consequence: Malicious or buggy plugins can crash or exploit the entire app; user must trust plugin sources.

• Scripting API: custom DSL vs existing language VM

  • Why: Simpler API surface and smaller distribution; delegates heavy computation to plugins or external tools.
  • Consequence: Limited scripting capability for complex data transformations; users may need C++ plugins for performance-critical tasks.

• Does not handle persistent cloud synchronization; local sync and manual export only
• Does not provide authentication or multi-user access control; single-user device app
• Does not run clipboard manager as privileged daemon; runs under user session only
• Does not support real-time clipboard monitoring across network; local OS clipboard access only
• Does not implement end-to-end encryption by default; encryption is opt-in plugin
• Does not work on mobile platforms (iOS/Android); desktop-only (Linux, macOS, Windows)

1. Qt 6 dependency is heavy and requires platform-specific toolchain setup (XCode on macOS, MSVC/MinGW on Windows, gcc/clang on Linux). 2) Clipboard access on Linux typically requires X11 or Wayland session; running in headless/SSH environment will fail. 3) macOS 13+ requirement is enforced (doc.qt.io/qt-6/macos.html); older versions not supported. 4) CMakePresets.json may define required CMake variables; check before custom cmake invocation. 5) miniaudio dependency is downloaded via GitHub Actions custom action (.github/actions/download-miniaudio/); network access required during build.

• System Clipboard Monitoring — The core functionality of CopyQ depends on hooking into OS clipboard change events; understanding X11 SelectionNotify/X11 Clipboard vs. Windows WM_CLIPBOARDUPDATE vs. macOS NSPasteboard notifications is critical for fixing platform-specific clipboard bugs.
• Qt Signals and Slots — CopyQ's event-driven architecture relies on Qt's signal/slot mechanism for clipboard monitoring, UI updates, and command execution; understanding this pattern is mandatory for modifying any interactive feature.
• MIME Types and Data Formats — CopyQ stores multiple clipboard formats (text/plain, text/html, image/png, image/jpeg, application/custom) in a single entry; managing MIME type negotiation and format conversion is essential for clipboard compatibility across applications.
• System Tray / Freedesktop Notifications — CopyQ integrates with system trays (Qt QSystemTrayIcon) and may use freedesktop D-Bus for notifications; this integration is fragile across Linux desktop environments and requires understanding of tray protocols.
• JavaScript Engine Embedding — The scripting API embeds a JavaScript interpreter for user-defined commands; understanding script sandboxing, QJSEngine bindings to C++ objects, and security implications is critical for extending or debugging automation features.
• CMake Cross-Platform Build Configuration — CopyQ's CMakeLists.txt orchestrates platform detection (Linux/Windows/macOS), conditional compilation, and dependency resolution across fundamentally different system APIs; modifying build logic requires CMake expertise.
• Persistent Data Storage (Tabs and History) — Clipboard entries must survive application restart; understanding how CopyQ serializes and deserializes tab data (likely SQLite or file-based storage) is necessary for features like encryption, backup, and tab management.

• erpalma/filterpedia — Similar clipboard utility but lightweight alternative; useful for understanding different architectural approaches to clipboard monitoring.
• libreoffice/core — LibreOffice also manages clipboard with multi-format support; shares similar challenges in handling text, HTML, images, and custom formats.
• Qt/qtbase — CopyQ's primary UI/system integration framework; understanding Qt's QClipboard and QApplication is essential for modifying clipboard logic.
• hluk/CopyQ-plugins — Official plugin/extension repository for CopyQ; demonstrates how to extend CopyQ with custom commands and integrations.
• ksnip/ksnip — Another Qt-based clipboard/screenshot utility on Linux; similar desktop integration patterns and multi-platform CI/CD approach.

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 missing documentation for scripting-api.rst features with code examples

The docs/scripting-api.rst file exists but lacks concrete examples for the JavaScript API. The CLAUDE.md, HACKING, and source-code-overview.rst suggest this is a scriptable clipboard manager, but the scripting API documentation needs paired examples showing common use cases (filtering items, custom commands, data transformation). This directly supports the 'advanced features' described in the README and would reduce support questions.

• [ ] Review existing docs/scripting-api.rst to identify missing API functions
• [ ] Cross-reference AGENTS.md and docs/command-examples.rst for real-world script examples
• [ ] Add 3-5 concrete code examples (e.g., 'Create a custom clipboard filter', 'Build a todo list command')
• [ ] Link examples to docs/commands-script.rst and ensure consistency
• [ ] Test examples in a local CopyQ instance before merging

Add integration tests for clipboard synchronization across tabs (docs/synchronize-*.rst features)

The docs reference synchronization features (docs/synchronize-config.png, docs/synchronize-formats.png) and session management (docs/sessions.rst), but there's no evidence of dedicated test coverage for cross-tab data sync. Given the project has platform-specific build workflows (Linux/macOS/Windows), multi-tab synchronization edge cases are high-risk. New tests would prevent regressions across platforms.

• [ ] Examine existing test structure in src/ or tests/ directory (not shown in file list, determine location)
• [ ] Write tests covering: tab sync on data copy, format preservation during sync, session persistence
• [ ] Test on at least 2 platforms using GitHub Actions matrix (extend build-linux.yml, build-macos.yml patterns)
• [ ] Add test documentation referencing docs/sessions.rst and docs/synchronize-*.rst
• [ ] Verify codecov.yml is updated if coverage thresholds exist

Create CONTRIBUTING.md with contributor-specific workflow (referencing HACKING and CLAUDE.md)

The repo has HACKING (development guide) and CLAUDE.md (Claude AI assistant config), but no CONTRIBUTING.md for external contributors. The .github/ISSUE_TEMPLATE exists but lacks a contribution workflow. For an active project with Weblate translations and multi-platform CI, new contributors need clear steps for: building locally, testing on their platform, running pre-commit checks (.pre-commit-config.yaml exists), and the CMake/Qt build process.

• [ ] Extract relevant build steps from docs/build-source-code.rst and HACKING
• [ ] Document the CMake/CMakePresets.json workflow specific to Linux/macOS/Windows
• [ ] Link to .pre-commit-config.yaml and document required checks (codespell.yml workflow)
• [ ] Add section on running tests and verifying codecov locally before pushing
• [ ] Include translation contribution workflow (reference .weblate and hosted.weblate.org badge in README)

1. Add test coverage for clipboard format detection (image/HTML/text handling in src/) — test files likely sparse given C++ codebase; identify missing unit tests and write them. 2) Expand docs/command-examples.rst with real-world scripting examples for common workflows (auto-paste on hotkey, clipboard filtering rules) — documentation-only contribution with low barrier. 3) Implement or document platform-specific clipboard permission handling for newer macOS/Windows versions (sandbox restrictions, clipboard access prompts) — relevant to active platform support and likely flagged in open issues.

CopyQ shows a reasonable security posture as a clipboard manager with encryption capabilities. The primary concerns are outdated documentation dependencies and the need for cryptographic audit of custom encryption implementation. The codebase demonstrates security awareness through inclusion of encryption plugins and documentation on password protection. However, the security score is moderately reduced due to: (1) pinned but outdated Sphinx dependencies requiring updates, (2) custom cryptographic implementation that should undergo professional audit, (3) lack of visible security policy documentation, and (4) limited visibility into C++ dependency management. The encryption-related functionality is critical for a clipboard manager and warrants professional security review. No obvious injection vulnerabilities, hardcoded credentials, or infrastructure misconfigurations are apparent from the file structure provided.

• Medium · Outdated Sphinx Dependencies — docs/requirements.txt. The documentation dependencies specify sphinx==7.2.6 and sphinx-rtd-theme==1.3.0. These versions may contain known vulnerabilities. Sphinx 7.2.6 was released in September 2023 and is no longer the latest stable version. Newer versions include security patches and bug fixes. Fix: Update to the latest stable versions of sphinx and sphinx-rtd-theme. Use flexible version constraints (e.g., sphinx>=7.3.0,<8.0.0) instead of pinned versions to receive security updates while maintaining compatibility.
• Medium · Encryption Plugin with Unverified Implementation — plugins/itemencrypted/. The codebase includes a custom encryption plugin (itemencrypted) which is a security-critical component. Without access to the actual implementation, it's unclear whether the encryption follows cryptographic best practices, uses authenticated encryption (AEAD), or properly handles key derivation. Fix: Conduct a thorough cryptographic audit of the encryption implementation. Ensure use of well-established libraries (libsodium, OpenSSL) rather than custom crypto. Verify AEAD mode encryption, proper key derivation (PBKDF2/Argon2), and secure random number generation.
• Low · FakeVim Plugin with Potential LGPL Exception — plugins/itemfakevim/fakevim/LGPL_EXCEPTION.TXT. The itemfakevim plugin includes an LGPL_EXCEPTION.TXT file, suggesting special license terms. This may indicate code reuse that requires careful license compliance and potential security review of third-party components. Fix: Document all third-party dependencies and their licenses. Ensure LGPL compliance and review security advisories for the upstream FakeVim project. Consider pinning versions of third-party plugins.
• Low · Missing SECURITY.md File — Repository root. The repository lacks a SECURITY.md file to document security policies, vulnerability disclosure procedures, and supported versions for security updates. Fix: Create a SECURITY.md file following GitHub's recommended format, including vulnerability reporting procedures, security patch policy, and supported versions.
• Low · Incomplete Dependency Specification — CMakeLists.txt and subprojects. Only documentation dependencies are visible in the provided context. The main application likely has C++ dependencies managed by CMake that are not visible. Without seeing the full dependency tree, potential supply chain risks cannot be fully assessed. Fix: Implement dependency scanning using tools like OWASP Dependency-Check or Snyk. Maintain an SBOM (Software Bill of Materials). Regularly audit C++ and system-level dependencies for known vulnerabilities.

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.