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/keepassxreboot/keepassxc 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 4d ago
• 33+ active contributors
• Distributed ownership (top contributor 26% of recent commits)
• Other licensed
• CI configured
• Tests present
• ⚠ Non-standard license (Other) — review terms

_{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 keepassxreboot/keepassxc repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/keepassxreboot/keepassxc.

What it runs against: a local clone of keepassxreboot/keepassxc — 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 keepassxreboot/keepassxc | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch develop exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 34 days ago | Catches sudden abandonment since generation |

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

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

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

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

# 4. Critical files exist
test -f "CMakeLists.txt" \\
  && ok "CMakeLists.txt" \\
  || miss "missing critical file: CMakeLists.txt"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f ".github/CONTRIBUTING.md" \\
  && ok ".github/CONTRIBUTING.md" \\
  || miss "missing critical file: .github/CONTRIBUTING.md"
test -f "SECURITY.md" \\
  && ok "SECURITY.md" \\
  || miss "missing critical file: SECURITY.md"
test -f "cmake/CompilerFlags.cmake" \\
  && ok "cmake/CompilerFlags.cmake" \\
  || miss "missing critical file: cmake/CompilerFlags.cmake"

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

KeePassXC is a cross-platform password manager that creates, opens, and encrypts databases in the KDBX format (KeePass-compatible). It stores usernames, passwords, URLs, attachments, and notes in an offline encrypted file with features like password generation, advanced search patterns, and customizable entry groups. The core capability is local-first, client-side encryption with zero cloud dependency. Monolithic C++ Qt application with CMake build system. Core architecture splits into cmake/ (build configuration with platform-specific checks like macOS biometry in cmake/compiler-checks/macos/), docs/ (AsciiDoc documentation), and src/ (inferred main application code not fully listed). Platform support abstraction via conditional compilation: macOS uses Touch ID/Watch support (control_*.mm), Linux/Windows use PCSC for smartcards, Windows uses resource version info.

Security-conscious individuals and organizations who need offline password management across Windows, macOS, and Linux. Power users requiring advanced features like custom fields, password generation, and encrypted attachment storage. System administrators maintaining KeePass-compatible databases across teams.

Highly mature and production-ready. The project has official OpenSSF Best Practices certification, active TeamCity CI/CD pipeline, codecov integration tracking test coverage, and regular releases. The codebase is predominantly C++ (4.8MB) with CMake build system, indicating years of development stabilization. Development remains active with organized GitHub issue templates and PR workflow.

Low risk for a password manager. The project has comprehensive security-focused licensing (GPL-2, GPL-3, LGPL, MIT, BSD), dedicated SECURITY.md file, and OpenSSF best practices adherence. Main risks: platform-specific code (Objective-C++ for macOS, PCSC for smartcards) may have edge cases; dependency on external crypto libraries (Botan, QREncode, Minizip) requires careful vetting. Single-maintainer risk mitigated by active community contributions visible in repo structure.

Active development visible in GitHub workflows (codeql.yml, copilot-setup-steps.yml), recent contributor onboarding documentation (.github/copilot-instructions.md), and organized issue templates distinguishing bug reports, feature requests, and prerelease bugs. The project maintains continuous integration and code quality scanning. CHANGELOG.md and version management suggest regular release cycles.

Clone the repository: git clone https://github.com/keepassxreboot/keepassxc.git && cd keepassxc. Install build dependencies (CMake, Qt5/Qt6, Botan crypto library). Build with: mkdir build && cd build && cmake .. && make -j$(nproc). Consult INSTALL.md for platform-specific build instructions and dependency lists.

Daily commands: After build: Launch the compiled binary (typically ./build/src/keepassxc on Linux). GUI application opens interactively. For testing: Build includes test suite invoked via make test in the build directory. No server startup required; purely client-side application.

• CMakeLists.txt — Root build configuration defining all project dependencies, compiler flags, and platform-specific compilation rules—essential for understanding the entire build pipeline and architecture decisions.
• README.md — Primary project overview describing KeePassXC's purpose, supported platforms, and feature scope—mandatory reading for contextualizing all contributions.
• .github/CONTRIBUTING.md — Official contribution guidelines, coding standards, and pull request workflow expectations specific to this project.
• SECURITY.md — Security policy and vulnerability disclosure process critical for understanding threat model and handling security-sensitive code changes.
• cmake/CompilerFlags.cmake — Compiler security and optimization flags that enforce code quality standards and cross-platform compatibility.
• .clang-format — Code formatting standards enforced across the entire codebase—required reference for maintaining consistent style in pull requests.

• CMake Build System (CMake 3.x, C++17, platform-specific headers (Security.framework, PCSC, XDG)) — Orchestrates compilation, applies security compiler flags, detects platform capabilities, manages external library integration, and generates platform-specific deployment artifacts
  • Failure mode: Build fails if dependencies missing, incorrect compiler flags applied, or

Add a new platform-specific feature (e.g., biometric unlock)

1. Create a compile-time check in cmake/compiler-checks/{platform}/ to detect feature availability (cmake/compiler-checks/macos/control_biometry_support.mm)
2. Add CMake custom find module in cmake/ to locate required native libraries (PCSC, Security framework, etc.) (cmake/FindPCSC.cmake)
3. Add conditional compilation flags to cmake/CompilerFlags.cmake for platform-specific code paths (cmake/CompilerFlags.cmake)
4. Update CMakeLists.txt subdirectory configuration to include platform-specific source directories (CMakeLists.txt)

Add a new cryptographic algorithm or dependency

1. Create a new CMake find module in cmake/ (e.g., cmake/FindNewLibrary.cmake) to locate and verify the library (cmake/FindBotan.cmake)
2. Update CMakeLists.txt to conditionally enable the new dependency and link it to relevant targets (CMakeLists.txt)
3. Add compiler security flags for the new dependency in cmake/CompilerFlags.cmake if needed (cmake/CompilerFlags.cmake)
4. Update CHANGELOG.md to document the new cryptographic feature for users (CHANGELOG.md)

Contribute a code change

1. Read .github/CONTRIBUTING.md to understand branching strategy, commit message format, and review expectations (.github/CONTRIBUTING.md)
2. Format code using clang-format configuration before committing (.clang-format)
3. Ensure builds pass on all platforms using cmake/CompilerFlags.cmake as the authority for warnings-as-errors (cmake/CompilerFlags.cmake)
4. Submit PR which will trigger GitHub Actions CodeQL analysis in .github/workflows/codeql.yml (.github/workflows/codeql.yml)

• CMake — Cross-platform build system enabling single codebase compilation on Windows, macOS, and Linux with platform-specific customization via custom find modules and compiler checks.
• Botan Cryptography Library — Provides FIPS-aligned symmetric and asymmetric encryption, key derivation, and hashing required for password database encryption and TOTP/PassKey support.
• PCSC (Smart Card API) — Enables hardware security key support for authentication and cryptographic operations on all platforms via a standard interface.
• Objective-C++ (macOS) — Allows native integration with macOS Security framework for Touch ID and Apple Watch biometric authentication at compile-time with graceful degradation.

• Compile-time platform feature detection (control_*_support.mm) rather than runtime dynamic loading

  • Why: Simpler deployment model and guaranteed ABI compatibility; avoids complex fallback logic
  • Consequence: Feature set is locked at build time per platform; users cannot enable features post-installation (e.g., installing PCSC libraries). Simplifies security review and testing matrix.

• CMake custom find modules (FindBotan.cmake, FindPCSC.cmake) instead of vcpkg/Conan package managers

  • Why: Maintains flexibility for distro-specific paths on Linux and enterprise environments; avoids heavy dependency manager overhead
  • Consequence: Contributors must manually verify library locations across platforms; increased burden on build troubleshooting for new developers.

• Security flags enforced at CMake level (CompilerFlags.cmake) rather than per-file pragmas

  • Why: Guarantees all code receives the same hardening (stack canaries, ASLR, DEP); prevents accidental opt-outs in security-critical code
  • Consequence: Cannot selectively disable hardening for performance-critical paths; may impact performance on resource-constrained platforms like embedded Linux.

• Cloud synchronization (KeePassXC is a standalone client; sync is via file sharing or KeeShare protocol only)
• Server-side authentication (no centralized account system; all credential management is local-only)
• Real-time collaborative editing (database locking prevents simultaneous multi-user edits)
• Browser native implementation (relies on separate KeePassXC-Browser extension for browser integration)

KDBX format version compatibility: code must support both KDBX3 and KDBX4 formats (mentioned in README) — format changes break database compatibility. Platform-specific crypto requirements: Botan library must be compiled with specific cipher support. Smartcard support (PCSC) requires pcscd daemon running on Linux — absence causes silent feature degradation. macOS biometry requires entitlements during code signing (see cmake/MacOSCodesign.cmake.in). Transifex integration (.tx/config) suggests translation workflow — strings must be marked for i18n. Qt version selection (Qt5 vs Qt6) during CMake configuration affects binary size and feature availability.

• KDBX Format (Keepass Database XML) — Understanding the KDBX format version compatibility (v3 vs v4) is essential for any database reading/writing code — breaking format support silently locks users out of their passwords
• Authenticated Encryption with Botan Crypto Library — KeePassXC delegates all encryption to Botan; contributors modifying crypto logic must understand authenticated encryption to prevent information leakage or tampering vulnerabilities
• Platform-Specific Feature Detection via CMake — The cmake/compiler-checks/ directory demonstrates conditional compilation for biometry (macOS), smartcards (PCSC), and version resource generation — understanding compile-time feature detection prevents runtime crashes on unsupported platforms
• Qt Framework Signal/Slot Architecture — KeePassXC GUI is built with Qt; understanding signal/slot decoupling and meta-object compilation (MOC) is required for any UI changes or event handling modifications
• Cross-Platform Code Signing and Entitlements — macOS and Windows binary distribution requires code signing (see cmake/MacOSCodesign.cmake.in, cmake/WindowsCodesign.cmake.in); biometry features fail silently without proper entitlements, making testing difficult
• PCSC (PC/SC) Smartcard Interface — The optional PCSC support for hardware security keys uses platform-specific daemon communication; understanding PCSC lifecycle prevents deadlocks and resource leaks in credential storage workflows
• Offline-First Encryption Architecture — KeePassXC's core selling point is zero network dependency — any code path that assumes online connectivity or cloud sync breaks the security model and user expectations

• keepassx/keepassx — Original KeePassX project that KeePassXC is a community reboot of, providing historical reference for design decisions
• dlech/KeePass2.x — Upstream KeePass 2.x for Windows that defines KDBX format specification and feature set that KeePassXC maintains compatibility with
• bitwarden/clients — Modern alternative password manager with cross-platform support; users evaluate both for similar offline/cloud capability trade-offs
• 1Password/1password-teams-open-source — Enterprise password manager often compared with KeePassXC for organizational deployments and format compatibility concerns
• emersion/pass — Unix password-store implementation representing minimal alternative approach; ecosystem users switch between approaches based on simplicity vs features

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 comprehensive unit tests for CMake helper modules in cmake/ directory

The cmake/ directory contains critical build system helpers (CLangFormat.cmake, CodeCoverage.cmake, CompilerFlags.cmake, and platform-specific modules like KPXCMacDeployHelpers.cmake, MacOSCodesign.cmake.in, WindowsCodesign.cmake.in) but there appear to be no dedicated test suites validating these modules. This is high-value because build system failures can silently affect all contributors and releases. Testing CMake modules ensures cross-platform builds remain reliable and prevents regressions in code signing, deployment, and compiler flag handling.

• [ ] Create tests/cmake/ directory with CMake test utilities following CMake/CTest best practices
• [ ] Add unit tests for cmake/CompilerFlags.cmake validating flag application across GCC/Clang/MSVC
• [ ] Add integration tests for cmake/KPXCMacDeployHelpers.cmake and cmake/MacOSCodesign.cmake.in validating macOS-specific deployment
• [ ] Add tests for cmake/WindowsCodesign.cmake.in validating Windows code signing setup
• [ ] Integrate CMake tests into existing CI workflow (.github/workflows/) to run on each commit

Create missing documentation for browser integration feature based on browser-related assets

The docs/ directory contains 10+ images related to browser integration (browser_advanced_settings.png, browser_extension_.png, browser__settings.png, browser_fill_credentials.png) but the main documentation files (GettingStarted.adoc, UserGuide.adoc) likely don't comprehensively document this feature. This is high-value for user onboarding and reduces support burden. A dedicated browser integration guide would help users understand KeePassXC's browser extension capabilities.

• [ ] Create docs/BrowserIntegration.adoc documenting the browser extension workflow
• [ ] Reference the existing images in docs/images/ (browser_extension_connect.png, browser_extension_association.png, browser_custom_browser_configuration.png, browser_confirm_access_dialog.png) with step-by-step setup instructions
• [ ] Document browser-specific database and entry settings shown in browser_database_settings.png, browser_entry_settings.png, browser_group_settings.png
• [ ] Add troubleshooting section for common browser extension issues
• [ ] Link new guide from UserGuide.adoc and GettingStarted.adoc

Add GitHub Actions workflow for validating CMake configuration across platforms

The .github/workflows/ directory exists with codeql.yml and other workflows, but there's no dedicated CMake validation workflow. Given the repo's complexity (cross-platform C++, multiple optional dependencies like Botan, Minizip, PCSC, QREncode, Readline via cmake/Find*.cmake modules), a CMake configuration validation workflow would catch build system errors early. This prevents contributors from discovering CMake issues only during local builds or CI failures.

• [ ] Create .github/workflows/cmake-validate.yml workflow file
• [ ] Add CMake syntax validation step using cmake --version and cmake -P for linting
• [ ] Add configuration tests for common scenarios: Linux with all deps, Linux with minimal deps, macOS build, Windows build (using matrix strategy)
• [ ] Validate all CMake find modules (FindBotan.cmake, FindPCSC.cmake, FindQREncode.cmake, etc.) resolve correctly
• [ ] Run workflow on pull_request events to provide immediate feedback to contributors

• Add test coverage for KDBX3 → KDBX4 migration logic. Check if tests exist in src/ for format conversion (format upgrade is a critical security path and test gaps are likely).
• Expand INSTALL.md with distribution-specific package manager instructions. The file exists but likely lacks Fedora/Arch/NixOS build instructions — cross-platform docs often have gaps.
• Create developer documentation for smartcard (PCSC) feature integration. The cmake/FindPCSC.cmake exists but platform-specific smartcard behavior (Windows vs Linux PCSC interaction) is rarely documented, making contributions difficult.

KeePassXC demonstrates a strong security posture with OpenSSF Best Practices certification, established vulnerability reporting channels, and responsible disclosure processes. The main gaps identified are: (1) inability to assess current dependency vulnerabilities due to missing manifest files, (2) need to verify that CMake template files (.in) don't contain embedded secrets, and (3) ensuring platform-specific security features are thoroughly documented. The codebase structure shows good security practices with separate licenses for multiple components and organized security channels. No critical hardcoded secrets, SQL injection patterns, or obvious misconfigurations were detected in the visible file structure. Recommend conducting regular SBOM analysis and maintaining dependency version locks.

• Low · Missing Dependency Manifest Analysis — CMakeLists.txt and cmake/Find*.cmake files. No package dependency files (package.json, requirements.txt, Cargo.toml, etc.) were provided in the analysis. This prevents assessment of known vulnerable dependencies. KeePassXC uses C++ with CMake, but specific versions of dependencies like Botan, Minizip, and QREncode cannot be verified. Fix: Provide dependency version specifications and regularly scan with tools like OWASP Dependency-Check or Snyk to identify vulnerable transitive dependencies.
• Low · Potential Hardcoded Configuration Paths — cmake/MacOSCodesign.cmake.in, cmake/WindowsCodesign.cmake.in. The repository contains CMake configuration files that may embed hardcoded paths or build-time secrets. Files like cmake/MacOSCodesign.cmake.in and cmake/WindowsCodesign.cmake.in could potentially contain credentials or sensitive signing information if not properly managed. Fix: Ensure signing credentials are provided via environment variables or secure CI/CD secrets, not embedded in configuration files. Audit .in template files to ensure no secrets are committed.
• Low · Platform-Specific Security Checks May Have Gaps — cmake/compiler-checks/macos/, cmake/compiler-checks/ptrace_deny_attach.cpp. The codebase includes platform-specific biometric authentication checks (macOS Touch ID, Watch support, ptrace_deny_attach). These compiler checks are good, but the security implications of each platform's biometric implementation should be thoroughly documented and tested. Fix: Maintain security documentation for platform-specific features and ensure regular security audits of biometric integrations. Consider adding compile-time warnings if security-critical features are disabled.
• Medium · Incomplete Security Policy Documentation — SECURITY.md. The SECURITY.md file appears truncated in the provided content, ending mid-sentence at 'bona f'. The complete security policy and vulnerability disclosure details are not visible for full analysis. Fix: Ensure SECURITY.md is complete and clearly documents: PGP key for encrypted submissions, expected response timeframes, supported versions receiving security updates, and coordinated disclosure timeline.

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.