KeePassXC — Material

Installer transition: this fork now targets unsigned Squirrel.Windows packages as its sole supported installation and update format. The generated executables are intentionally unsigned and may display Unknown Publisher or SmartScreen warnings.

Run build.bat for the native application, build-installer.bat for verified Setup.exe, RELEASES, and full-package output, or download-dependencies.bat to prepare the pinned user-scoped toolchain. Each accepts /s or --silent.

Before packaging, the installer script verifies that HEAD is readable and the source checkout has no tracked or untracked changes. Diagnostics report bounded change counts without printing paths.

A Windows-only fork of KeePassXC whose interface is being rebuilt in Material Design 3.

Complete feature delivery in progress

Browser credential-access confirmation removal and complete required-feature acceptance are being developed together for one final release. Intermediate release and documentation publication are held. The expanded inventory names 90 feature families and 115 surfaces; its 95 focused structural checks pass, but no current native interaction evidence is implied. See the acceptance inventory and handoff for the remaining work.

October 3 startup integration state

The documentation website has a narrow navigation repair: complete tab labels retain intrinsic widths within the scrollable Material tab strip, and the build packages the existing project favicon. Four focused built-output checks pass after three observed baseline failures. New rendered acceptance is pending; see navigation verification.

The startup surprise contract now combines its 1% draw, persisted off switch and credential/error/update exclusions with the shared motion controller. At 7cb43f654ef2cc908a76a5a739bddfda2aa29c52, three isolated offscreen suites passed 167 checks (127 + 7 + 33), with no failures, skips or timeouts. These are behavioral results, not native or packaged acceptance. All 40 feature articles and the four promoted choice controls remain present. Product completeness stays 0/105,788 current verified capability cells.

October 3 choice-control delivery state

Browser, sharing and SSH choice controls now use the shared Material combo-box class in four existing fields. The browser, keeshare and sshagent owners compiled at 3cb79c5ce840e494b00e6cbcd22cc2fa1d14759f; this establishes controller compatibility, not native interaction, accessibility or rendering acceptance. The documentation catalogue retains its prior 39 articles and adds this article as number 40.

The hidden-desktop controller is installed at source e6e42f2066d539256d6480401d7cef867f2b8dfe. Its quiet standard-input/output transport exposes 58 tools and passed native-backend installation smoke with a synthetic Qt fixture: hidden launch, capture, background close and owned teardown. That image is not KeePassXC evidence. KeePassXC profile/history isolation remains blocked pending the owner's scope decision, and no packaged lifecycle has run.

Release v2.8.30301 binds 91772a166def5e44f60dd49501f5882d7190287c. The coordinator downloaded and verified all seven required assets. Native acceptance remains unverified, and the promotion is a later source unit awaiting integration and delivery. See the required smoke sequence. The September repair verification record separates the passing focused native checks and published website from still-unverified installed dragging, updates, and the incomplete full feature inventory.

The database lifecycle repair record tracks the October database-opening crash, Save As result, history initialization and Windows filename-lifetime repairs. Local compilation and database checks passed. The keyless-open and Save As regressions were observed failing before their repairs and passing afterward. All 15 focused GUI processes and ten selected history cases pass. An initial history directory beyond 260 characters remains an open limitation; the packaged create, save, quit and reopen sequence is pending. The installed launch crash is not yet claimed resolved.

The cryptography, the KDBX format handling, the browser and SSH integrations and the command line tool are upstream KeePassXC and are deliberately untouched. What changed is what you look at: the stock Qt styling — BaseStyle (4 860 lines), LightStyle, DarkStyle, phantomcolor and all four .qss sheets — has been deleted and replaced by one token-driven design system.

This is a personal fork and it is unfinished — see Status before you rely on it. For the official, supported password manager, use keepassxreboot/keepassxc.

Windows only

Linux support has been removed from this fork, not merely disabled. Gone from the tree: the freedesktop.org Secret Service server, the XDG desktop portals, D-Bus, the X11 and Wayland auto-type backends, PolKit quick unlock, nixutils, and Snap / Flatpak / AppImage packaging. The CI builds and tests Windows only. macOS sources are still present but are neither built nor tested here.

If you need Linux or macOS, use upstream.

The interface

The window is a Material 3 shell: an 88 px navigation rail, a 64 px top app bar, a database tab strip, and a five-destination stack. Ctrl+Shift+F opens a command palette listing all 218 QActions with their menu path and shortcut.

Destination	State
Vault	Material three-pane screen with remembered user widths and deferred first-visible splitter restoration. Focused offscreen sizing checks pass; native geometry acceptance remains pending. See vault pane sizing.
Reports	Material screen — password health, breach and reuse findings, database statistics as stat cards
History	Material screen — local Git-backed revision history embedded in encrypted database saves, with diff and restore
Changelog	Material screen — every released version, searchable and date-filterable, exportable to Markdown
Settings	Material screen — appearance, language, behaviour and integrations, plus spec sheets for individual settings

The combined menu, motion and vault-sizing source passed 90 focused Qt entries at 2e7683ffb5dd6e7912e5f7f61b48674ec1a54a90, with zero failures or timeouts across five isolated offscreen processes. These checks do not prove packaged interaction, native geometry, screen-reader behavior or full feature completeness. The handoff records exact target counts, executable hashes and remaining scope. Release-grade smoke verification and genuine current captures for chat, repository evidence, README and the documentation website remain pending through the approved isolated route; the existing historical images do not establish that acceptance.

Appearance is a runtime setting, not a build flag

Everything the interface draws resolves through one design system, so the whole application restyles live:

• Theme — light or dark, or follow Windows.
• Seed colour — KeePassXC blue, baseline purple, vault green or signal amber. The seed drives the primary and container roles; surfaces, outlines and status colours flip with the light/dark family.
• Density — compact, comfortable or spacious, changing every list, tree and table row height (40 / 52 / 64 px).
• Interface font — family, size scale and weight, with a CJK-safe fallback.

No widget in src/ hard-codes a colour. They ask the theme for a semantic role, so a seed or density change repaints the application without a restart.

Cross-cutting behaviour

• Regex builder — a guided builder (character classes, anchors, quantifiers, groups, flags, sample text, live matches and captures) reachable from every search bar. Plain-text search stays the default; regex is an explicit opt-in, and query, pattern, flags and mode stay in sync both ways.
• Non-blocking notifications — informational, success and progress messages are snackbars anchored bottom-centre, never modal dialogs. Modals are reserved for decisions you must make: confirmations, destructive gates and credential steps. Dismissed notifications stay reviewable in the notification centre.
• Language modes — English, playful Hong Kong Cantonese, or bilingual, with an independent 1–5 humour slider per language. The humour styles the voice only: what happened, what is affected and what is irreversible stay exact at every level.
• Passkey clipboard transfer — passkeys can be copied and pasted as keepassxc-passkey:v1:<base64>. Copying a private key raises a warning that cannot be suppressed and defaults to Cancel, because base64 is encoding, not encryption: anything you paste that string into can read the key.

Accessibility

Keyboard reachability, visible focus, correct roles and names, contrast and reduced-motion respect are treated as defects when broken, not as polish. So is visual clipping and mis-sizing at 100/125/150/200 % display scale and in the longest localized strings.

Password manager features

Inherited from upstream KeePassXC and intact:

• Create, open and save KDBX 3 and KDBX 4 databases; everything is encrypted at rest
• Entries organised into groups, with tags, attachments, custom attributes and field references
• Password and passphrase generator
• TOTP storage and generation
• YubiKey / OnlyKey challenge-response
• Auto-Type into any application
• Browser integration for Chrome, Firefox, Edge, Chromium, Vivaldi, Brave and Tor Browser, including passkeys — extensions register themselves per-user on first run
• Windows Hello quick unlock
• Import from CSV, 1Password, Bitwarden, Proton Pass and KeePass1
• Export to CSV, XML and HTML
• SSH Agent integration
• Command line interface (keepassxc-cli)
• Additional ciphers: Twofish and ChaCha20

Removed with Linux: freedesktop.org Secret Service.

See CHANGELOG.md for release history and docs/topics/KeyboardShortcuts.adoc for shortcuts.

Building

Requires Visual Studio 2022+ with the C++ workload, Qt 6.8 msvc2022_64, CMake 3.16+ and Ninja. Native dependencies (Botan 3, minizip, libqrencode, zlib, readline) are declared in vcpkg.json and resolved by vcpkg.

From an x64 Native Tools Command Prompt:

cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug -DCMAKE_PREFIX_PATH=C:/Qt/6.8.3/msvc2022_64 -DCMAKE_TOOLCHAIN_FILE=%VCPKG_ROOT%/scripts/buildsystems/vcpkg.cmake

cmake --build build

Longer instructions, including the test invocations, live in INSTALL.md.

Screenshots

Screen capture is allowed by default: the window shows up in screenshots, recordings and screen sharing like any other application. View ▸ Allow Screen Capture turns that off, and the choice is remembered. With capture blocked KeePassXC calls SetWindowDisplayAffinity(WDA_EXCLUDEFROMCAPTURE) on its top-level windows: they stay visible and hit-testable on the monitor, but PrintWindow, BitBlt and CopyFromScreen return black and a desktop grab returns the windows behind them. --prevent-screencapture forces that state for one run; --allow-screencapture forces the opposite.

Layout of the UI code

src/gui/material/
  MaterialTheme.*        colour roles, seeds, density, type scale, palette
  MaterialStyleSheet.*   the single generated stylesheet for stock Qt widgets
  MaterialStyle.*        QProxyStyle for what a stylesheet cannot express
  MaterialIcons.*        Material Symbols names resolved to bundled SVGs
  MaterialShell.*        the window interior: rail, app bar, tab strip, stack
  Material<Component>.*  buttons, chips, switches, cards, search bars,
                         snackbars, overlays, item delegates, screens and
                         spec sheets

Adding a surface means composing these components and asking the theme for roles — not writing another stylesheet.

Status

Honest state of the rewrite, measured rather than remembered:

• Design parity is proven, not assumed. Every one of the nine checked-in design references under design/ has a real capture of the reference and of the built application at the identical tuple, a labelled side-by-side comparison, a machine-readable diff and a hand-written Material Design 3 audit (design/parity/). Mismatch runs from 4.8 % (entry sheet) to 20.4 % (regex builder). Repaired this pass: the window now draws its own Material title bar in place of the OS caption, the regex builder is the design's workbench, the Reports cards carry the reference anatomy and the vault root lists every entry. The audits list what is still open: the app bar content, vault health chips and group filter, and smaller differences on Settings, Appearance, History and Changelog.
• The feature inventory is fail-closed and currently red. The interface completeness contract registers 89 canonical features, 106 named native and website surfaces, and 998 capability contracts. All 172 original source-assessment rows and their historical links remain, with six added summaries. node scripts/check-feature-inventory.mjs --summary reports 0 of 105,788 current surface/capability cells verified, spanning 9,434 incomplete surface/feature groups. These are coverage obligations, not a count of distinct implementation defects. Acceptance requires configuration, implementation, localized copy, documentation, focused tests, persistence where applicable, and genuine candidate-bound interactions and captures. Passing the separate schema checks establishes inventory integrity only; source presence and historical captures do not establish current product completion.
• Done since the previous status — the legacy status bar under the shell is gone; the welcome screen shows the running version, revision and the exact updated-at time of that revision; the dim sum surprise is a ten percent draw with no opt-out; the command palette is on Ctrl+Shift+F; build.bat exports its own MSVC environment; releases carry a CI-measured line count, workflow timing and a dim sum code name with the public photo attached.
• Not done — everything the inventory marks missing: School mode, narrator, scheduled settings, per-element appearance editors and toy locks, tab groups and docking, the authenticator, bulk actions and exports, offline docs, ADHD modes, the file converter and Ollama manager, the documentation site, and the rest of the list.

HANDOFF.md carries the full picture and the next owner's route.

Captures

Every image below is a capture of the built application, taken by handle on an off-screen desktop through design/parity/capture.mjs at the commit named beside it, in light theme and bilingual mode with the key-file fixture database. The reference and the pixel diff for each one sit beside it under design/parity/evidence/<row>/.

The shell: rail, app bar, tab strip and the vault destination (1440×920) — commit cd7d2de63404

Vault destination (1440×860) — commit cd7d2de63404

Reports destination (1200×860) — commit cd7d2de63404

History destination (1200×860) — commit cd7d2de63404

Changelog destination (1200×860) — commit cd7d2de63404

Settings destination, General page (1280×860) — commit cd7d2de63404

Appearance destination (1200×860) — commit cd7d2de63404

Entry sheet (1280×860) — commit cd7d2de63404

Regex builder overlay over the vault (1040×720) — commit cd7d2de63404

Not captured yet: dark theme, the compact and minimum widths, 125 to 200 percent display scales, dialogs and error states. The clipping matrix under design/parity/evidence/clipping/ holds captures at the compact and expanded widths that are not yet promoted into this list.

Lines of code

Counted by the committed node scripts/count-lines.mjs; the same table is published in every release and the release body is the record. The figures below are the local measurement at e09d6e28; release v2.8.9301 measured d7e8adba at 340,795 project lines because it counted the clipping-matrix probe dumps as generated project lines, a classification corrected in the counter after that release.

Area	Lines
Application source (src, excluding the Material layer)	120,815
Material UI (src/gui/material)	34,025
Design references and parity tooling	33,883
Tests	30,868
Everything else in the project total	14,490
Project total	234,081

Vendored fonts and runtime, bundled third-party sources, upstream documentation sources and translation files are counted separately and held out of the project total (509,232 lines). Of the project total, 23,615 lines across 20 files are generated by tooling. Attribution by surviving git blame line: agents 91,434 (39.1 %), people 142,647 (60.9 %).

How long a person would have taken (estimate, not a measurement): the 210,466 hand-written project lines at a sustained 60 to 100 finished lines per working day of C++, Qt and tooling code give roughly 2,100 to 3,500 working days, or about 9 to 15 person-years. Vendored, generated and translation lines are excluded, exactly as in the count above, and the range is deliberately wide because a line of cryptography or installer lifecycle code is not a line of documentation.

Contributing

Bug reports and ideas for the upstream password manager belong in the KeePassXC issue tracker. Issues specific to this fork's interface belong here.

Contributors adhere to the project's Code of Conduct. See CONTRIBUTING for the upstream workflow.

Generative AI

Substantial parts of this fork's Material interface were written with agent-assisted development. All submissions go through review regardless of workflow.

License

KeePassXC code is licensed under GPL-2 or GPL-3. The Material interface layer added by this fork carries the same licence. Third-party file licensing is detailed in COPYING.

Vault category search update

The vault category search implementation adds a local tag filter, metadata-only entry matching, clear controls, and query resets. Build and native acceptance are pending. See the feature article.