Installation

luvus ships as a single static binary (~3 MB) with no runtime dependencies. Pick whichever channel you prefer:

curl -fsSL https://luvus.dev/install.sh | sh

Downloads the right prebuilt binary for your OS/arch from GitHub releases and puts it on your PATH (/usr/local/bin or ~/.local/bin). macOS builds ship for both Apple silicon and Intel, Linux for x86_64 and arm64, and FreeBSD for amd64.

brew install RizRiyz/luvus/luvus

Installs the same prebuilt binary, so there is no Rust toolchain and no compile step. Upgrading later: brew upgrade luvus.

Every release attaches a .deb and a .rpm for x86_64 and arm64 on the releases page. Download the one for your arch and install it:

# Debian / Ubuntu
sudo apt install ./luvus_0.9.2_amd64.deb

# Fedora / RHEL
sudo dnf install ./luvus-0.9.2-x86_64-unknown-linux-musl.rpm

luvus is a single static binary, so the package has no hard dependencies and drops it straight into /usr/bin. The tools luvus optionally calls (git, openssh-client, xclip) are Recommends, so a desktop gets them by default while a minimal server can skip them without breaking the install. Good for provisioning a Linux server.

luvus ships a flake, so it works on NixOS and any machine with Nix. Every command below needs flakes enabled (add experimental-features = nix-command flakes to nix.conf, or pass --extra-experimental-features "nix-command flakes").

Run it once, without installing anything:

nix run github:RizRiyz/luvus

Install into your user profile (puts luvus on your PATH):

nix profile install github:RizRiyz/luvus
nix profile upgrade luvus          # update to the latest later
nix profile remove luvus           # uninstall

NixOS (declarative): add the flake as an input and pull it into your system packages, then sudo nixos-rebuild switch:

{
  inputs.luvus.url = "github:RizRiyz/luvus";

  outputs = { self, nixpkgs, luvus, ... }: {
    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";          # or aarch64-linux
      modules = [{
        environment.systemPackages = [ luvus.packages.x86_64-linux.default ];
      }];
    };
  };
}

Home Manager (declarative), with luvus added as a flake input:

home.packages = [ inputs.luvus.packages.${pkgs.system}.default ];

Build a local binary without installing (result at ./result/bin/luvus):

nix build github:RizRiyz/luvus

Dev shell: the Rust toolchain plus everything luvus needs, for hacking:

nix develop github:RizRiyz/luvus
# then, inside it:
cargo run -- --local

The package bakes the tools luvus calls at runtime into its PATH (git, gh, ps, ssh), so the git tab and agent detection work on NixOS out of the box, where nothing is on a global PATH. It builds reproducibly from the committed Cargo.lock, with no C toolchain needed.

Prefer the flake over install.sh on NixOS. The script’s static binary does run (and lands in ~/.local/bin), but it installs imperatively, outside Nix, and wires up none of those runtime tools, so the git tab and agent detection would silently not work.

luvus is not in nixpkgs yet, so the flake above is the Nix path for now. Want to help get it there? The repo’s nix/ folder has a ready package definition and a submission guide.

irm https://luvus.dev/install.ps1 | iex

Or download the …-x86_64-pc-windows-msvc.zip from the releases page and put luvus.exe on your PATH. Run luvus inside Windows Terminal. Live cwd tracking and the shell integration hook aren’t available on Windows, but agent session resume still works.

Check your setup

luvus doctor

doctor probes the optional tools luvus integrates with and tells you what each unlocks:

Tool	Unlocks
`git`	the git tab · worktrees · orchestration workers
`gh` (authenticated)	PRs, issues, and PR detail in the git tab
`ssh`	remote sessions (`luvus --remote host`)

None are required for the core multiplexer: panes, tabs, agents, and resume all work without them.

The optional agent hook

Live agent status and session resume work with zero setup. For precise session ids and lifecycle events used by sound alerts and module automation, install the integration hook for your agent:

luvus integration install claude     # or: copilot · codex · antigravity · opencode

Also available from Settings → Integrations inside luvus. luvus integration uninstall <agent> removes only luvus’s hook and never touches the agent itself.

Upgrading

Use one command to check first and install only when a newer release exists:

luvus update

Direct macOS and Linux installs are downloaded from the matching GitHub Release, checked against its published SHA-256 digest, and replaced only after the downloaded binary reports the expected version. Homebrew and Cargo installs update through their package manager. Nix and Linux system packages are never overwritten; the command reports the matching package-manager action instead. On Windows it checks for the release, then prints the PowerShell installer command because Windows cannot replace the executable while it is running.

The running server is left alone so active panes are not interrupted. After a successful update, reload it when you are ready:

luvus server restart         # restart only the selected session
luvus server restart --all   # restart every currently running session

Stopped sessions remain stopped. If you restart only the selected session, other running named sessions remain uninterrupted until you select them; the session switcher then detects the older server version, restarts that target, and completes the switch.

Development binaries under target/debug or target/release are never overwritten by luvus update. Rebuild those from source instead.

Where luvus keeps its state

Everything lives in ~/.luvus/ (override with $LUVUS_HOME): your configuration, the auto-saved session snapshot, and the orchestration ledger. The directory is created owner-only (0700).

The default session keeps its files directly in this directory. Named server sessions store their runtime files under ~/.luvus/sessions/<name>/. Preferences, manifests, skills, and module installations remain shared.