Orbit

Orbit is a personal-first, reusable desktop layer for Arch Linux, Wayland, and Hyprland. It owns the complete graphical session and grows into a keyboard-first command center without taking ownership of shell, editor, or interactive-terminal configuration.

Orbit now owns and reconciles the live graphical session. Its resident service and OpenTUI launcher replace Wofi for applications, typed commands, clipboard history, open-window control, and tmux sessions.

Scope

Orbit will own:

• Hyprland, Hyprlock, Hypridle, Waybar, Mako, launcher, wallpaper, and session startup configuration.
• Required Arch packages for the graphical session.
• An idempotent apply/doctor workflow driven from this Git checkout.
• A single orbit CLI with resident-daemon and transient-client modes.
• A terminal-rendered omni menu, global copy/paste behavior, desktop themes, and provider integrations.

Orbit will not own shell/editor configuration, the normal terminal configuration, development or compute toolchains, Steam installation, GPU drivers, or other Linux distributions. ../dotfiles and Orbit remain operationally independent.

Design

• Product definition
• Architecture
• Package architecture and migration
• Delivery roadmap
• Provider manifests, indexers, and panels

Installation and reconciliation

Install or update to the latest checksum-verified release, then run Orbit's interactive desktop reconciliation:

curl -fsSL https://code.olsen.cloud/envs/desktop/raw/branch/main/scripts/install.sh | bash

The script atomically installs the supported Linux x64 binary at $HOME/.local/bin/orbit. Re-running the same command updates Orbit. From a source checkout, build and install the current revision instead:

./bin/orbit install

That source installer provisions the pinned tools and locked dependencies, runs the complete quality gate, builds and installs one standalone executable, materializes embedded desktop defaults, displays the exact reconciliation plan, requires explicit confirmation, applies that reviewed digest, refreshes an active Hyprland session, and finishes with orbit doctor.

Task is the shared local and CI entry point:

mise install
task install
task ci:quality
task build
./bin/orbit capabilities --json
./bin/orbit apply --dry-run
./bin/orbit apply --expect-plan <digest>
./bin/orbit doctor
./bin/orbit menu
./bin/orbit menu --provider clipboard
systemctl --user status orbit-daemon.service
./bin/orbit panel orbit search

orbit apply never mutates from an unreviewed plan. Run the dry-run, then pass its digest to orbit apply --expect-plan <digest>. Automation should add --json; stdout is one versioned document and prompts are forbidden. orbit install is human-only and uses the same reviewed-plan operation.

$XDG_CONFIG_HOME/hypr/hyprland.lua is seeded once and remains user-owned. It imports Orbit's managed $XDG_CONFIG_HOME/hypr/orbit.lua; add any native Hyprland Lua after that import for machine-specific devices, monitors, bindings, or other overrides. Reconciliation updates the imported core without overwriting the user-owned file.

Releases

Pushes to main update a draft release from conventional commits after the quality and compliance workflows pass. Review that draft in Forgejo, then publish it by pushing its annotated tag:

git tag -m "vX.Y.Z" vX.Y.Z
git push origin vX.Y.Z

The tag pipeline reruns the quality gate, builds orbit-linux-x64, and attaches the binary plus its SHA-256 checksum to the release.

Launcher controls

Omni search is the built-in orbit/search panel. Provider panels are loaded on demand and may reuse Orbit's shared OpenTUI components and theme tokens to match its style.

• Before typing, omni search shows only provider panels.
• Type to search panel names plus records from shared indexes.
• Clipboard records remain private to the Clipboard History panel; opening a provider panel searches that provider's shared and internal indexes.
• Ctrl+J / Ctrl+K move down / up. Arrow keys remain accepted.
• Enter opens a panel or runs the primary action: launch an application or command, focus a window, or switch the most recently active tmux client to a session.
• Ctrl+O opens the selected record's action chooser. Window close, explicit tmux attach-in-new-terminal, and tmux session kill are secondary actions there.
• Escape returns from the action chooser or provider panel, then closes the menu.

Use task format to apply formatting. task ci:quality covers formatting, source/documentation linting, strict TypeScript, and Bun tests with coverage.