Skip to main content

crates

Compass is a Cargo workspace (crates/) plus the TypeScript extension SDK and runtime (src/typescript/). This page says what each part is for and where to start on a given kind of change. Each crate's own module documentation (cargo doc --workspace --no-deps --open) goes into the detail, and the architecture decisions record why it is shaped this way.

The rule that shapes it​

compass-ui is presentation: it turns state into Iced widgets and input into messages. The decisions live in crates that can be tested without a display, mostly compass-core. Shared crates must not depend on Linux-specific ones; crates/compass-platform/tests/the_seam_holds.rs checks that, and the crates allowed to be Linux-bound are marked below. AGENTS.md has the full rules.

The binary and the UI​

CrateWhat it is
compassThe compass command: the CLI, the engine (compass serve, the IPC server and the services it runs), and the wiring of every other crate. Linux-bound.
compass-uiThe Iced launcher window: every view, the settings, the onboarding flow.

Application logic​

CrateWhat it is
compass-coreApplication state and the decisions about it: the app index and ranking, frecency, compass.json, commands, the calculator, snippets, themes, the extension stores, Rhai and script commands' manifests, and more. No UI dependency.
compass-searchFuzzy matching: the matcher and the weighted-field searchable trait every list uses.
compass-xdgDesktop entries, MIME associations, XDG directories and terminals.

Storage​

CrateWhat it is
compass-dbSchema migrations shared by every database. The migrations match upstream Vicinae's, so an existing profile keeps working.
compass-sqlcipher-sysOpens Compass's databases: rusqlite over SQLCipher, keyed. One of the two crates allowed unsafe (ADR-0019).
compass-cryptoThe clipboard history's encryption at rest, and the keys kept in the desktop keyring.
compass-clipboardThe clipboard history store.
compass-local-storagePer-extension key/value storage, as the Raycast LocalStorage API sees it.
compass-oauth-storeExtensions' OAuth token sets.

Extensions​

CrateWhat it is
compass-extension-apiThe seam every extension tier sits behind.
compass-worker-hostRuns TypeScript extension workers: the framing to the Node runtime, the API services they call, cgroup memory limits. Linux-bound.
compass-sandboxThe Landlock filesystem boundary and seccomp filter a worker runs behind, and compass-sandbox-exec, which applies them.
compass-scriptRhai scripts, the in-process extension tier (RHAI-SCRIPTS.md).
compass-ipcThe engine's Unix-socket protocol, used by the CLI and the launcher window.
compass-figuraGenerates the TypeScript bindings for the extension runtime's protocol from figura/*.fig (make figen).

Platform​

CrateWhat it is
compass-platformWhat the platform can be asked to do, as traits, so other platforms can be added as backends.
compass-platform-linuxThe Linux implementations: launching, and compositor IPC for KWin, Hyprland and niri, among others. Linux-bound.
compass-waylandWayland protocols beyond what Iced provides: activation, layer shell, foreign toplevels, data control, hotkeys, the virtual keyboard. Used on wlroots compositors, never on GNOME. Linux-bound.
compass-wayland-protocolsGenerated bindings for Wayland protocols no published crate carries yet. Linux-bound.
compass-wayland-foreignTurns the toolkit window's raw Wayland handles into proxies. The other crate allowed unsafe. Linux-bound.
compass-portalsThe XDG desktop portals Compass uses, such as GlobalShortcuts. Linux-bound.
compass-shellThe client for the Compass GNOME Shell extension (extensions/gnome-shell). Linux-bound.
compass-powerPower actions over systemd-logind. Linux-bound.
compass-mediaMedia players over MPRIS. Linux-bound.
compass-input-serverThe small privileged helper behind snippet keyword expansion. Linux-bound.
compass-a11y-linuxThe launcher window's accessibility tree on AT-SPI, through AccessKit's Unix adapter (ADR-0022). Linux-bound.

Tests​

CrateWhat it is
compass-testkitShared fixtures, corpora and the harnesses described in RENDER-HARNESSES.md.

TypeScript and other directories​

PathWhat it is
src/typescript/apiThe extension SDK, published as @vicinae/api so store extensions run unchanged, and the vici CLI that builds and develops extensions.
src/typescript/extension-managerThe extension runtime the engine runs under Node (make extension-runtime).
src/typescript/raycast-api-compatThe Raycast API compatibility layer.
extensions/gnome-shellThe GNOME Shell helper extension.
extensions/rhai-examplesThe Rhai scripts Compass ships.
extensions/raycast-linux-overrides.jsonPer-extension Linux fixes for Raycast extensions, including the host programs each may run (RAYCAST-LINUX-SHIM.md).
figura/The IDL for the extension runtime's protocol.
packaging/Flatpak, AppImage, Arch, Nix and Homebrew packaging (packaging/README.md).

Where to start​

You want to change…Start in
How results are found or rankedcompass-core (root_items, rank, apps) and compass-search
A settingcompass-core::config and compass-core::settings_catalog, then the view in compass-ui
How a view looks or responds to keyscompass-ui
A builtin commandcompass-core::commands for what it is, compass-ui for its view
What extensions can dothe SDK in src/typescript/api, the service in compass-worker-host, the protocol in figura/
What extensions may touchcompass-sandbox and compass::extension_runner
A desktop integrationcompass-platform for the trait, compass-platform-linux or compass-wayland for Linux
Packagingpackaging/ and scripts/packaging/