Release: Wombat

Wombat is the current DocsHub architecture.

Read the Roadmap

Vitra Ubuntu GNOME development guide

The current development path requires:

• Ubuntu with GNOME Shell 50 on Wayland;
• Rust 1.85 or newer and Cargo;
• systemd user services;
• GNOME extension tooling and schema compilation; and
• Python 3.11 or newer with PySide6 6.8 or newer for the UI.

Additional GNOME releases should not be assumed compatible until they have been tested and declared upstream.

Install the development build

From a Vitra source checkout:

./scripts/install-gnome-dev.sh

The script builds the locked Rust workspace in release mode and installs files for the current user. It installs the agent and UI launcher under ~/.local/bin, UI files under the user data directory, the GNOME extension under the user extension directory, and a user service under the systemd user configuration directory. It then reloads systemd, enables and restarts the agent, compiles the extension schema, and attempts to enable the extension.

GNOME may not notice a newly installed extension until the next session. If the installer reports that it could not enable the extension, log out and back in, then run:

gnome-extensions enable [email protected]

Open history

After installation, launch the normal UI with:

vitra-ui

For a source-tree UI without installing it:

./scripts/run-ui-dev.sh

On the supported GNOME development environment, Super+V opens compact quick history. Type to filter locally, use the arrow keys to select an item, press Enter to copy and dismiss, or Escape to close. The shortcut is stored in the extension’s show-history GSettings key and can be changed without modifying the extension source.

The full UI supports refresh, keyboard navigation, pin/unpin, confirmed single-item deletion, and copy with duplicate-capture suppression. Closing the window terminates the Python/Qt UI; the Rust agent remains available.

Diagnostics

systemctl --user status vitra-agent.service
gnome-extensions info [email protected]
~/.local/bin/vitra-agent --recent-summary
~/.local/bin/vitra-agent --delete-item ITEM_ID

The recent summary intentionally prints IDs, timestamps, and byte lengths—not clipboard contents. Treat the command output as metadata that may still reveal activity timing.

If capture does not work, confirm all three layers separately:

1. the user service is active;
2. the GNOME extension is installed, enabled, and compatible with the running Shell version; and
3. the desktop session has a usable Secret Service credential provider.

Vitra fails closed when it cannot load the history key; it must not silently fall back to plaintext history.

Development checks

cargo test --workspace --no-fail-fast
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo fmt --all --check

The Rust workspace forbids unsafe code and treats the full Clippy and pedantic lint groups as warnings, with CI-style invocation promoting warnings to errors. The PySide UI has its own tests and Ruff configuration under ui/pyside/.

The development installer changes files in the current user’s local binary, data, GNOME extension, and systemd configuration directories. Review the script before using it on a session whose existing setup must not be changed.