v0.1.5

Familiar Desktop v0.1.5

Familiar now recognises registered plugin panels that share Quickshell's application ID. RSS Feed uses its RSS glyph, and recognised panels keep their own identities, windows and pins. The same icon rendering is used in the dock, Windows taskbar and app folders.

• Fix Home and Downloads shortcuts killing ordinary file-manager handlers after an eight-second timeout (#82).
• Fix generated trackpad gestures and Command editing shortcuts on the supported Hyprland Lua API; send balanced key-down/key-up events (#76).
• Qualify Omarchy palette references and signal subscriptions for Qt 6.12, with matching Quickshell and patched Core coverage (#78).
• Give the Home shortcut the matching home-outline glyph (#83).
• Skip the extra Chrome/Chromium titlebar by default; a saved setting lets users opt back in (#67).
• Give settings, app identity, window history, drag interactions, visibility and appearance explicit owners; share repeated app/widget and preference components.
• Refresh the marketplace preview and replace the old prototype code map with the current architecture and validation commands.

General, Windows and Mac layouts remain available. The proposed Mac-only direction and further splitting of the largest components are deferred.

Updating

Personal pins, app folders, settings and rollback snapshots are preserved. If Command editing shortcuts or Familiar gestures were already enabled on an older installation, reset and reapply those preferences in Familiar to regenerate their managed Lua. Exact older generated files can be replaced safely; personal edits remain protected.

The native installation command remains:

omarchy plugin add https://github.com/tcballard/omarchy-plugin-familiar-desktop --enable

Finish first-time setup inside Familiar. Development testing uses the exact source/binary bundle and rollback procedure in DEVELOPMENT.md.

Compatibility and limits

Supported target: Linux x86_64, Omarchy Quattro and Hyprland 0.56.2 ABI efb50993780079460b0cbed1363e2166a2de1d9f_aq_0.15_hu_0.14_hg_0.5_hc_0.1_hlg_0.6. ARM64 and other Hyprland ABIs are not covered by this release's binary evidence.

Automated desktop tests cover Qt 6.11.2 / Quickshell 0.3.1 and Qt 6.12.0 / Quickshell 0.3.2 against pinned Core revisions. Familiar's palette fix does not repair an unpatched Core or a mismatched Qt/Quickshell installation.

Panel discovery uses enabled bar-widget registrations and exact registered names/window titles. Ambiguous, unregistered or differently titled panels keep the existing fallback; a panel must expose a managed window to appear in the dock. The RSS smoke fixture tests panel identity and interaction without feed data or network access.

Full migration to Omarchy's official titlebar package (#74) remains open. The existing guard pauses Familiar's bundled titlebars when that package is present. Broader physical monitor, scaling and app coverage remains open; test and promotion evidence is recorded in RELEASE-0.1.5.md.

Thanks

• @dmalmq for the detailed folder-handler reproduction in #82 and the Home icon report in #83.
• @gfisek for the native Lua dispatcher findings, working API examples and suggested regression coverage in #76.
• @maddada for the browser titlebar report in #67.
• Tom Ballard (@tcballard) for the RSS panel/icon report, code review and XPS testing recorded in PR #81.
• rosakodu for the original omarchy-dock foundation.

Exact source: 439f97480bb0803f32137dcb700fbb939dc959ff. Verified main build.

v0.1.4

Familiar Desktop v0.1.4

Windows mode uses one full-width bottom taskbar: 48px tall at the default font scale, with 32px app icons and a labelled Familiar settings button. It now works when Familiar was enabled only as a service or placed in Plugin Drawer. General and Mac restore the previous bar arrangement and height while retaining personal widgets and settings.

• Fix the widget load error on newer Omarchy shells caused by an unsupported button property.
• Keep Familiar's hidden Plugin Drawer copy out of the bar's click routing so the visible settings button and neighbouring bar widgets receive their own clicks.
• Fix Mac dock hover previews and clicks after the dock slides into view by keeping its clickable area aligned with the visible card.
• Enable window actions when opening an app menu or switching between apps without requiring a window-row click; retain explicit selections across refreshes and recover when the selected window closes.
• Reduce the app menu to five everyday actions and three visible window rows; omit the window list for single-window apps and show only launch/pin actions when no windows are open.
• Preserve Familiar’s service/bar placement through development installation and rollback, including later personal moves and inline settings.
• Place Familiar immediately to the right of Agents on fresh installs, including the candidate installer; updates and repairs preserve an existing placement.
• Address the initial-install 404 reported in #79: release automation uploads and checks the verified binaries before publishing, then tests the exact public onboarding URLs and their committed checksums. Failed downloads show the URL and release page inside setup.
• Cover both original and current shell APIs in disposable desktop smoke tests.

Thanks

• Matteo Murgida (@teomurgi) for confirming the initial-install failure in #79 and contributing the release-download fix, diagnostics and regression tests in #80.
• @lucasmedeirosleite, @austinwilkerson and @Evansbee for additional reproductions and installation findings in #79.
• Mohamad Yahia (@maddada) for requesting a single Windows-style taskbar in #68.
• rosakodu for the original omarchy-dock foundation.
• Tom Ballard (@tcballard) for documenting the installation report, XPS debugging and desktop testing.

Installation and compatibility

Add Familiar with:

omarchy plugin add https://github.com/tcballard/omarchy-plugin-familiar-desktop --enable

Finish setup inside Familiar. Existing failed installations must update their plugin source to this release before retrying; an old v0.1.3 checkout still requests v0.1.3 assets. The existing v0.1.3 tag is unchanged.

Supported: Linux x86_64, Omarchy Quattro and Hyprland 0.56.2 ABI efb50993780079460b0cbed1363e2166a2de1d9f_aq_0.15_hu_0.14_hg_0.5_hc_0.1_hlg_0.6. The official-titlebar-package guard remains in place. Official-package migration (#74), Qt 6.12 palette compatibility (#78), and the reported input shortcuts/gestures issue (#76) are not included in this hotfix.

Personal pins, settings and rollback snapshots are retained. Release automation verifies the public onboarding downloads against the reviewed binary checksums. Review the release checklist and smoke-test handoff for build identity, acceptance and rollback.

Exact source: 3e72a99f2077b99726029870363d63569dfc8fec. Verified main build.

Familiar Desktop v0.1.2

Install Familiar once, then finish setup inside Familiar.

• Native plugin installation opens first-run setup with Windows or Mac controls.
• Backend and window-control downloads show progress, errors and retry in the same screen.
• Verified existing installs skip onboarding; setup and repair remain available in Windows settings.
• Downloaded binaries must match checksums committed in the source.

Install

omarchy plugin add https://github.com/tcballard/omarchy-plugin-familiar-desktop --enable

Click Set up Familiar. No second terminal command is needed. Setup requires curl, jq, coreutils, Linux x86_64 and the supported Hyprland ABI. Missing tools and incompatible desktops are reported inside Familiar.

Tested source

Tom tested v0.1.1-rc.4 on the XPS and approved release on 6 October 2026. v0.1.2 updates version metadata, binary pins and release documentation without changing runtime behaviour from that candidate. The rebuilt backend passes the committed checksum check.

Exact stable source: 9b948cd4d80e002eff88698d752f08268934b93c.

Supported target: Omarchy Quattro, Linux x86_64, Hyprland 0.56.2 commit efb50993780079460b0cbed1363e2166a2de1d9f, ABI efb50993780079460b0cbed1363e2166a2de1d9f_aq_0.15_hu_0.14_hg_0.5_hc_0.1_hlg_0.6. Other ABIs are refused. Exhaustive monitor/scaling/lifecycle coverage and marketplace approval are not claimed.

Remove

bash ~/.config/omarchy/plugins/io.github.tcballard.familiar-desktop/uninstall.sh

Removal restores tracked windows and removes owned configuration, retaining personal settings and backups. Settings navigation/scrolling remains a follow-up in #28.

Full changes

Familiar Desktop v0.1.1

Familiar v0.1.1 makes everyday window handling feel more familiar—and fixes the installer hiccup from v0.1.0.

• Resize with the mouse. Enable border and corner dragging without holding a modifier.
• Choose Floating or Tiling. Apply the mode to eligible open windows and new ones. Fullscreen, pinned, grouped and hidden windows are skipped.
• Keep familiar controls close. Opt-in Command editing shortcuts, trackpad gestures and smoother dock cycling join more precise window focus and restore.
• Install through shell reloads. Setup retries transient “Target not found” responses while still reporting persistent failures.
• Verify the bytes you run. Backend and Hyprbars downloads must match digests committed in the reviewed source. Replacing a release binary and its neighbouring checksum together no longer passes verification.

The maintainer tested rc.3 on the XPS and approved this exact source for v0.1.1: a3d54f36d9f702e25c8424ad2cd4028f09f9999f. No runtime or UI changes were made after that acceptance. Required CI and release builds passed; this does not claim exhaustive multi-monitor/scaling coverage or marketplace approval.

Known follow-up: Settings has become too long and needs less scrolling. That cleanup is tracked in #28 for a later release.

Install or update

Run in an Omarchy Quattro terminal. Restore minimised windows first. This verifies the installer against the digest of the accepted build before running it:

(
  set -euo pipefail
  familiar_setup="$(mktemp -d)"
  cd "$familiar_setup"
  curl -fL --retry 3 https://github.com/tcballard/omarchy-plugin-familiar-desktop/releases/download/v0.1.1/install.sh -o install.sh
  echo "2a68b44fa80daff10af116edb43a8b43cfbdc08a8ef8520c39d2b51239dfa083  install.sh" | sha256sum --check --strict
  bash install.sh windows
  omarchy restart shell
)

Use mac for left-side controls. No GitHub login or compiler is required. Missing download tools may prompt for a package-manager password. Settings repair uses the installed checkout and the same source-pinned binary digests.

Supported target: Linux x86_64, Omarchy Quattro, Hyprland 0.56.2 commit efb50993780079460b0cbed1363e2166a2de1d9f, ABI efb50993780079460b0cbed1363e2166a2de1d9f_aq_0.15_hu_0.14_hg_0.5_hc_0.1_hlg_0.6. Unsupported ABIs are refused. Command aliases are opt-in; custom terminal classes require review.

Remove with:

bash ~/.config/omarchy/plugins/io.github.tcballard.familiar-desktop/uninstall.sh

Removal restores tracked windows and resets owned compositor preferences, retaining personal settings and backups. Existing v0.1.0 tags/assets remain unchanged. The source archive retains the preparation checklists; this release records the subsequent maintainer acceptance.

Full changes

v0.1.1-rc.4

Familiar v0.1.1-rc.4

Familiar now includes first-run setup inside the plugin. Choose a Windows or Mac layout and follow installation progress without opening another terminal.

Changes

• Install the backend and window controls through Familiar, with failure details and retry.
• Keep the dock hidden until setup succeeds; verified existing installs skip onboarding.
• Verify downloaded binaries against digests recorded in source.
• Coordinate setup with a shared controller, filesystem lock and incomplete marker for duplicate clicks and interrupted installation.
• Reopen setup from Windows settings.

Validation and scope

PR #30 passed Portable checks and Release binaries on main at 1ff730ad1a706d5a50f18e4c8091666e04ce3864. Publication additionally requires green checks for the exact tagged source, verifies artifact manifests and checksums, and downloads the uploaded bundle again before publishing.

This is an x86_64 Linux test candidate. Fresh native installation and the complete first-run flow on the XPS still require live acceptance. Automated checks do not establish live desktop acceptance or constitute a security audit.

The manifest/backend version remains 0.1.1; the candidate tag is v0.1.1-rc.4. This candidate does not replace the existing stable v0.1.1 release.

Exact source: 812f7a7a878be8f7b71c6f49feb52357cd1d7421. Verified main build.

v0.1.1-rc.3

Familiar Desktop v0.1.1-rc.3

A test build for the next round of XPS acceptance before final v0.1.1.

• Installation retries shell refresh while Omarchy reloads the plugin, avoiding the transient “Target not found” failure. Persistent failures still stop setup.
• Backend and Hyprbars downloads are checked against SHA-256 digests committed in the reviewed source. Replacing release assets and their accompanying checksums together no longer passes that check.
• Candidate installation fetches its exact source snapshot and verifies both bundled binaries against its committed digests before executing the backend. Release packaging also rejects rebuilt bytes that differ from those pins.
• Includes RC.2’s opt-in border resizing, Floating/Tiling for existing and new eligible windows, Command editing aliases, shortcut labels, trackpad gestures and smoother dock cycling.

Install for testing

Download familiar-v0.1.1-rc.3-linux-x86_64.zip and its .sha256 file into one directory:

sha256sum --check familiar-v0.1.1-rc.3-linux-x86_64.zip.sha256
mkdir familiar-v0.1.1-rc.3
unzip familiar-v0.1.1-rc.3-linux-x86_64.zip -d familiar-v0.1.1-rc.3
cd familiar-v0.1.1-rc.3
bash install-candidate.sh windows
omarchy restart shell

Use mac for left-side controls. For repair, rerun this candidate installer. Settings repair and standalone install.sh still target unpublished final v0.1.1 assets.

The adjacent ZIP checksum provides transport integrity, not independent authentication of the installer. Use a separately verified ZIP digest when available. Once trusted, the candidate installer obtains its binary pins from the exact Git snapshot. This is not a claim of signatures or marketplace approval.

Supported target: Linux x86_64, Omarchy Quattro, Hyprland 0.56.2 commit efb50993780079460b0cbed1363e2166a2de1d9f, ABI efb50993780079460b0cbed1363e2166a2de1d9f_aq_0.15_hu_0.14_hg_0.5_hc_0.1_hlg_0.6. Other ABIs are refused.

Acceptance still needed

Portable tests, installer fixtures, coordinated binary/checksum substitution regressions and release packaging run in CI. Real backend and Hyprbars downloads have also been exercised through the changed installers; compositor loading is not covered by that test.

Live XPS install/update, resizing, mode switching, dock restore, shortcuts, gestures, persistence, mixed scaling, multiple monitors and removal still require testing. Follow XPS-TEST.md in the bundle. Existing gesture conflicts can reject preferences; custom terminal classes need review before Command aliases are enabled.

Remove using:

bash ~/.config/omarchy/plugins/io.github.tcballard.familiar-desktop/uninstall.sh

Removal resets owned compositor preferences and restores tracked windows, retaining personal settings and backups. This is a prerelease; v0.1.0 remains the latest stable release. No existing tag or asset is replaced.

Exact source: a3d54f36d9f702e25c8424ad2cd4028f09f9999f. Verified main build.

v0.1.1-rc.2

Familiar Desktop v0.1.1-rc.2

The next test build brings the rest of the desktop feedback together.

• Resize with the mouse. Enable border dragging, then drag a window edge or corner without holding a modifier.
• Switch how windows behave. Floating and Tiling now act on eligible existing windows and set the mode for new ones. Fullscreen, pinned, grouped and hidden windows are skipped; tiling uses your current Hyprland layout and shortcuts.
• Use Command for editing. An opt-in setting adds Command copy, paste, cut, select all, undo and redo. Known terminals use Ctrl+Shift+C/V for copy/paste. The setting replaces the listed Super bindings until reset; it is not a global key swap.
• Choose familiar labels and trackpad gestures. Command/Option/Control labels, three-finger workspace swipes, four-finger Show Desktop/Restore and smoother dock window cycling are included.

Title bars remain part of Familiar, with optional Mac/Windows controls. Familiar stays one integrated plugin.

Try this RC

Download familiar-v0.1.1-rc.2-linux-x86_64.zip and its .sha256 file into the same directory:

sha256sum --check familiar-v0.1.1-rc.2-linux-x86_64.zip.sha256
mkdir familiar-v0.1.1-rc.2
unzip familiar-v0.1.1-rc.2-linux-x86_64.zip -d familiar-v0.1.1-rc.2
cd familiar-v0.1.1-rc.2
bash install-candidate.sh windows

Use mac for Mac-style title bars. Re-run the candidate installer for RC repair;
Settings repair and standalone install.sh target unpublished final v0.1.1 assets.
The bundle installs its exact built source and checks its files. Checksums beside
the download are not independent publisher attestations.

Supported target: Linux x86_64, Omarchy Quattro, Hyprland 0.56.2 commit
efb50993780079460b0cbed1363e2166a2de1d9f, ABI
efb50993780079460b0cbed1363e2166a2de1d9f_aq_0.15_hu_0.14_hg_0.5_hc_0.1_hlg_0.6.
Other ABIs are refused.

Test before enabling everything

Preferences are opt-in. Existing gesture conflicts can reject a choice; use the
separate desktop/workspace groups. Two-finger taps depend on system right-click
settings. Custom terminal classes need review before enabling Command aliases.
Mode switching reports skipped/failed windows; retry finishes partial changes.
Use configuration removes owned overrides without reconstructing old window
geometry. Disabling the shell plugin alone retains compositor preferences.

Automated checks run before publication. Live XPS resizing, gestures, shortcut
handling, mixed scaling and multi-monitor acceptance remain outstanding. Follow
XPS-TEST.md and RELEASE-0.1.1.md; this is a test prerelease, not final v0.1.1.
Remove using the installed plugin’s uninstall.sh, which restores tracked
windows and removes owned preferences while retaining backups.

Exact source: a2d56f33f9277390e05ef8639ed6e16fcd1acce3. Verified main build.

v0.1.1-rc.1

Familiar Desktop v0.1.1-rc.1

The first v0.1.1 test build is ready. This collects the window behaviour and installer changes before the next round of feedback.

• Keep your tiles the same size. Choose Windows → Floating to make newly opened windows overlap instead of splitting the tiled layout. This includes Super+Enter terminals. Existing windows keep their layout; Use configuration removes the preference.
• Land in the right window. Dock activation now focuses the selected window and centres the pointer using its current geometry. Right-click an app to choose a named window. New Window remains a separate action.
• Repair the installed version. Settings repair no longer fetches source through a tag. Release installers carry the exact built source SHA.

Minimise keeps the app running on a hidden workspace. Its dock entry restores it to the current workspace; there is no shrink-into-taskbar animation.

Try this RC

Download the familiar-v0.1.1-rc.1-linux-x86_64.zip asset and its .sha256 file into the same directory. From that directory:

sha256sum --check familiar-v0.1.1-rc.1-linux-x86_64.zip.sha256
mkdir familiar-v0.1.1-rc.1
unzip familiar-v0.1.1-rc.1-linux-x86_64.zip -d familiar-v0.1.1-rc.1
cd familiar-v0.1.1-rc.1
bash install-candidate.sh windows

Use mac instead of windows for Mac-style controls. The bundle verifies its files and installs its exact source commit. Read XPS-TEST.md and RELEASE-0.1.1.md inside the bundle. Re-run the candidate installer for RC repair: the Settings repair command and standalone install.sh target final v0.1.1 assets, which are not published yet.

Supported target: Linux x86_64 on Omarchy Quattro with Hyprland 0.56.2, commit efb50993780079460b0cbed1363e2166a2de1d9f, ABI efb50993780079460b0cbed1363e2166a2de1d9f_aq_0.15_hu_0.14_hg_0.5_hc_0.1_hlg_0.6. Other ABIs are refused.

Rust, Lua, QML, installer, cleanup and release-build checks pass before this RC is published. The new floating preference and pointer placement still need live XPS and multi-monitor/scaling testing. This is a prerelease for that testing, not the final v0.1.1 or a marketplace approval. More feedback is still being collected. Checksums beside downloads are not independent publisher attestations.

Remove using the installed plugin's uninstall.sh; restore minimised windows first if prompted. Personal preferences and recovery backups are retained.

Exact source: 2e28cdc43a59d4d7427cd7a59d40613ff1a9571f. Verified main build.

v0.1.0

Familiar v0.1.0 gives Omarchy a few familiar places to click: a dock, window controls and settings you can open from the bar.

• Find the right window. Launch an app, choose an open window by name, bring it here or arrange it on screen.
• Make room, then come back. Show Desktop hides eligible windows; Restore brings them back, with a recovery journal across shell reloads.
• Choose what feels comfortable. General, Windows and Mac layouts share your pins. Put the dock at the bottom, left or right. Optional title bars add close, minimise and maximise controls.
• Keep the everyday bits close. Centred settings, active shortcut help, optional Home/Downloads/Bin buttons, and separate Quit and confirmed Force Quit actions.
• Let Caps Lock mean Caps Lock. Choose Normal Caps Lock, Compose or your existing configuration. Both late keyboard bugs are fixed.

Install from an Omarchy Quattro terminal:

bash <(curl -fsSL https://raw.githubusercontent.com/tcballard/omarchy-plugin-familiar-desktop/v0.1.0/install.sh) windows
omarchy restart shell

Use mac for controls on the left. Restore minimised windows before upgrading. Installation uses prebuilt, checksum-verified Linux x86_64 components; no GitHub login, Rust toolchain or Hyprpm build is required.

Window controls require Hyprland 0.56.2 commit efb50993780079460b0cbed1363e2166a2de1d9f, ABI efb50993780079460b0cbed1363e2166a2de1d9f_aq_0.15_hu_0.14_hg_0.5_hc_0.1_hlg_0.6. Unsupported versions stop setup.

The maintainer approved rc.5 after XPS testing. Runtime source is unchanged from rc.5; formal preparation updates documentation and tag automation. Automated Rust, Lua, QML, installer and release-build checks cover the candidate. This is not a claim of exhaustive multi-monitor, scaling, application or fresh-profile lifecycle testing.

Remove Familiar with:

bash ~/.config/omarchy/plugins/io.github.tcballard.familiar-desktop/uninstall.sh

Removal restores journalled windows, resets owned keyboard/title-bar configuration and stops if cleanup fails. Settings, pins and backups remain.

The curated app collection is planned for v0.2.0. Paint, Notepad and Task Manager remain separate projects.

Found something awkward or broken? Open a bug report with your version, steps and a screenshot.

v0.1.0-rc.5

Familiar rc.5 brings the tested desktop changes together on main, ready for the next round of testing before v0.1.0.

Includes both Caps Lock fixes: Lua 5.5 compatibility and correct handling of blank Hyprland configuration diagnostics. It also includes dock positioning, settings persistence, theme-aware window controls and owned-configuration cleanup.

Since rc.4: the formal release installer now checks local files and compatibility, restores windows and disables controls before updating. Release CI distinguishes RC tags from final releases. Bug-report and feature-request forms are now available.

Download the attached ZIP, extract it, then run bash install-candidate.sh windows followed by omarchy restart shell. Use mac for left-side controls. Restore minimised windows first. No GitHub login or Rust toolchain is required.

Source: 377f8823c1b8a013131d75d614339bf569c9a68e. Both Portable checks and Release binaries passed on this exact main commit. The ZIP is the unchanged artifact from Release binaries run 37359006230.

ZIP SHA-256: 86831e8b43183cf2fc86b9b29235de44f8b10bb64cb9459b4b72304128978916.

Target: Omarchy Quattro, Linux x86_64, Hyprland 0.56.2 commit efb50993780079460b0cbed1363e2166a2de1d9f with ABI efb50993780079460b0cbed1363e2166a2de1d9f_aq_0.15_hu_0.14_hg_0.5_hc_0.1_hlg_0.6. The embedded package version remains 0.1.0; the prerelease tag identifies this test candidate.

This is a test prerelease. The bundle installs through the candidate installer; live validation of the formal release installer remains separate. Broader monitor, scaling, application and lifecycle acceptance is still open. See XPS-TEST.md and ROLLBACK.md in the bundle.