---
url: https://hyprpilot.kilic.dev/runtime/installation.md
---

# {{ $frontmatter.title }}

Hyprpilot is a single Rust binary. It resolves a session profile from layered config and `exec()`s into the vendor's native agent CLI — so the only hard runtime dependency is the vendor CLI you want to launch (`claude`, `codex`, `opencode`, or `amp`).

## Arch

Hyprpilot is published to the AUR in two flavors. Pick one — they conflict by design.

::: code-group

```sh [hyprpilot-bin]
# Prebuilt binary — tracks the latest GitHub Release.
yay -S hyprpilot-bin
```

```sh [hyprpilot-git]
# Builds from the latest `main` with cargo.
yay -S hyprpilot-git
```

:::

Both install the binary, the terminal `.desktop` entry, and the hicolor icons. Swap `yay` for `paru` or your AUR helper of choice.

## Building from source

If you are not on an Arch-like distro, build with a stock Rust toolchain — it is a plain Rust build with no webkit / gtk / node dependency:

```sh
git clone https://github.com/hyprpilot/hyprpilot
cd hyprpilot
cargo build --release
install -Dm755 target/release/hyprpilot ~/.local/bin/hyprpilot
```

A manual build only drops the binary; the AUR packages also install the desktop entry and icons. See [Development](../repository/development) for the pinned toolchain and `task` targets.

## The desktop entry

The AUR packages install a terminal-launcher `.desktop` file at `/usr/share/applications/hyprpilot.desktop`:

```ini
[Desktop Entry]
Type=Application
Name=hyprpilot
GenericName=Agent CLI launcher
Comment=Resolves a profile and execs your coding agent's native CLI.
Exec=hyprpilot
Icon=hyprpilot
Categories=Development;Utility;
StartupNotify=false
Terminal=true
```

`Terminal=true` means any XDG app launcher (rofi, wofi, fuzzel, the GNOME grid) lists **hyprpilot**; selecting it opens a terminal, runs the interactive profile picker, and execs the chosen agent in that terminal. Nothing extra to wire — installing the package is enough.

## Launch from a compositor keybind

If you prefer a keybind over an app launcher, bind a key to a terminal that runs hyprpilot. Bare `hyprpilot` opens the interactive picker; `hyprpilot <id>` skips straight to a profile.

::: code-group

```ini [Hyprland]
# ~/.config/hypr/hyprland.conf
bind = SUPER, RETURN, exec, foot -e hyprpilot
bind = SUPER SHIFT, RETURN, exec, foot -e hyprpilot engineer
```

```sh [Sway]
# ~/.config/sway/config
bindsym $mod+Return exec foot -e hyprpilot
bindsym $mod+Shift+Return exec foot -e hyprpilot engineer
```

:::

Swap `foot` for your terminal of choice (`kitty -e`, `alacritty -e`, `wezterm start --`, `gnome-terminal --`, …). The vendor TUI takes over that terminal until you exit it.

## Shell completion

Completion is dynamic: the shell calls hyprpilot back on every `<Tab>`, so it offers the session profile ids from your resolved config (agent and model as the description, the default marked), the overlay names under `~/.config/hyprpilot/profiles/` for `--config-profile`, and, for a codex profile, its approval and sandbox modes for `--mode`. claude, opencode and amp get no `--mode` candidates: hyprpilot passes their modes through as-is and keeps no list of them. The candidates follow the command line — `hyprpilot --config-profile work <Tab>` lists the work overlay's profiles. A config that does not load yields no candidates rather than an error.

Register it from your shell's startup file:

::: code-group

```sh [zsh]
# ~/.zshrc
eval "$(hyprpilot completion zsh)"
```

```sh [bash]
# ~/.bashrc
eval "$(hyprpilot completion bash)"
```

```fish [fish]
# ~/.config/fish/config.fish
hyprpilot completion fish | source
```

:::

`elvish` and `powershell` are supported too. `COMPLETE=<shell> hyprpilot` prints the same script.

The zsh script defines the completer as `_hyprpilot`, the name zsh plugin managers expect, and only calls `compdef` itself once `compinit` has run. So it also loads lazily, for example with znap:

```sh
znap function _hyprpilot '_hyprpilot() { :; }; eval "$(hyprpilot completion zsh 2>/dev/null)"'
compdef _hyprpilot hyprpilot
```

It also works as an autoload file: save it as `_hyprpilot` in a directory on `fpath` before `compinit` runs.

```sh
hyprpilot completion zsh > ~/.zfunc/_hyprpilot   # with fpath=(~/.zfunc $fpath) in ~/.zshrc
```

## After install

1. **Install a vendor CLI** — hyprpilot launches `claude`, `codex`, `opencode`, or `amp`; at least one must be on your `$PATH`.
2. **Configure at least one profile** — fresh installs ship agent defaults but **no** profile, and hyprpilot refuses to launch until one exists. The [Quickstart](./quickstart) walks you through it.

Because hyprpilot `exec()`s into the vendor CLI, it inherits your shell environment as-is — API keys, `$PATH`, and everything else the vendor needs are already present when you run it from a terminal. There is no long-lived process to keep hydrated.