Vitra

A fast, secure, cross-platform clipboard manager under active development.

Vitra uses a lightweight Rust agent for work that must remain running and an on-demand desktop UI for browsing and acting on clipboard history. Linux, macOS, and Windows are first-class targets; development currently happens on Ubuntu GNOME Wayland.

Current status

The Ubuntu text-capture vertical slice is working end to end:

• vitra-agent runs as a systemd --user service.
• A GNOME Shell 50 extension observes Wayland clipboard text.
• Captures cross an authenticated, length-bounded local socket.
• The Rust core validates and deduplicates observations.
• SQLite persists XChaCha20-Poly1305 encrypted history and serves authenticated, newest-first reads.
• The 256-bit history key lives in the native OS credential store, not beside the database.
• Configurable retention keeps 1–100,000 unpinned items (default 1,000) while preserving pinned entries, and authenticated IPC supports idempotent single-item deletion.
• An on-demand PySide6/QML window reads history over IPC, provides local search, refresh, keyboard navigation, copy with duplicate-capture suppression, pin/unpin controls, and confirmed single-item deletion, then exits completely when closed.
• The installed idle agent has remained well below the 10 MB resident target.

This is pre-alpha software. Encryption at rest, configurable retention, and single-item deletion are active, but broader platform capture, bulk history controls, corruption recovery, and security review remain before production use.

Architecture

GNOME extension / future native platform adapter
                    │
                    ▼
        authenticated local IPC
                    │
                    ▼
  Rust agent ──► core rules ──► SQLite history
       ▲
       │ versioned local IPC
       ▼
 on-demand PySide6/QML UI

• vitra-agent owns capture, authentication, storage, retention, and platform lifecycle integration.
• The UI never opens the database or watches the clipboard directly.
• Platform-specific capture stays behind explicit adapters.
• PySide6 with Qt Quick is the delivery UI baseline. Slint remains a measured, time-boxed alternative rather than a release dependency.

The rationale is recorded in ADR 0001.

Repository layout

crates/
  vitra-agent/      Agent service, local IPC, configuration, and lifecycle
  vitra-core/       Domain models, ingestion, and deduplication
  vitra-protocol/   Versioned authenticated wire messages
  vitra-storage/    SQLite schema and persistence
platform/
  linux/
    gnome-shell/    GNOME Wayland clipboard adapter
    systemd/        Linux user service
docs/               Decisions and UI benchmark notes
scripts/            Development installation helpers

Ubuntu GNOME development install

Requirements include Rust 1.85 or newer, Cargo, GNOME Shell 50, and systemd's user manager.

./scripts/install-gnome-dev.sh

The script builds and installs the optimized agent, installs the on-demand UI launcher under ~/.local/bin, starts the user service, installs the GNOME extension, and enables it. A newly installed extension may require one logout and login before GNOME Shell sees it.

Useful diagnostics:

systemctl --user status vitra-agent.service
gnome-extensions info vitra@zford.dev
~/.local/bin/vitra-agent --recent-summary
~/.local/bin/vitra-agent --delete-item ITEM_ID

The history summary reports only IDs, timestamps, and byte lengths. It never prints clipboard contents.

Launch the development UI on demand:

./scripts/run-ui-dev.sh
# After running the development installer:
vitra-ui

On GNOME, Super+V opens the compact quick-history mode. Type to filter, use the arrow keys to select, press Enter to copy and dismiss, or press Escape to close. The binding is stored in the extension's show-history GSettings key so it can be changed without modifying the extension source.

Development checks

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

Near-term roadmap

1. Add quick-panel paste activation and record successful Vitra paste usage.
2. Benchmark the PySide6 baseline against Slint using the working quick panel.
3. Add native Windows and macOS capture adapters and lifecycle integration.
4. Expand Linux capture beyond GNOME Wayland and validate supported GNOME releases.
5. Complete threat-model review, corruption recovery, and packaging hardening.

The v1 scope remains local-only. Cloud sync, accounts, OCR, AI features, and a plugin system are intentionally deferred.

Performance targets

• Agent idle memory: below 10 MB
• Agent idle CPU: effectively 0% outside platform observation requirements
• UI memory while open: below 80 MB
• UI process exits completely when closed

License

MIT. See LICENSE.