# Hover docs > Install Hover, hand your first task to an agent by typing or speaking, and learn the notch, the Agent office, approvals, quotas and your data. Current release: v3.9.0. Each section is also its own page: https://tryhover.co/docs/
.md (for example https://tryhover.co/docs/install.md). Index for agents: https://tryhover.co/llms.txt ## Introduction Hover puts AI agents to work in a notch at the top centre of your screen. At rest it is a slim black island that quietly shows your AI quotas and the agents at work. Hover your pointer over it and it expands into the **Agent office**: a small 3D office where Codex, Cursor, OpenCode, Claude Code and Kiro each work as a bot at a desk, in the project folder you chose. ![The Agent office with three bots at their desks](https://tryhover.co/shots/office.jpg) - **Give tasks** to the agent CLIs you already have, up to three at once. - **Or say them out loud**: press a shortcut, speak, press it again. See [Voice](https://tryhover.co/docs/voice.md). - **Approve risky steps** right in the notch, or let an agent run on its own. - **Watch your quotas** for Claude Code, Kiro, Codex and Cursor. - **Keep every session**, encrypted, and pick any of them back up with a reply. - **Undo a turn.** Hover keeps your folder before and after every answer; see [Checkpoints](https://tryhover.co/docs/checkpoints.md). - **Look over an agent's shoulder** with the [desk card](https://tryhover.co/docs/desk-card.md): its terminal, files, diff and pull requests. Hover is a native app written in Rust, for Windows and Linux, with a new Mac app on the same engine (see [Hover on macOS](https://tryhover.co/docs/macos.md)). There is no account, no server and no analytics. It is free and open source under the MIT license. ## Install Hover runs on Windows, Linux and macOS. Download the newest build from [release v3.9.0](https://github.com/4regab/Hover/releases/tag/v3.9.0) on GitHub, where every file is attached. For the Mac, see [Hover on macOS](https://tryhover.co/docs/macos.md). | Platform | File to download | | --- | --- | | Windows 10 / 11 (x64) | `Hover-Setup-3.9.0.exe` | | Ubuntu 22.04+ and Debian-based (x64) | `hover_3.9.0_amd64.deb` | | Any other Linux (x64) | `hover-3.9.0-linux-x86_64.tar.gz` | | macOS 14+ ([guide](https://tryhover.co/docs/macos.md)) | `Hover-3.9.0-macos-arm64.dmg` (Apple silicon) or `Hover-3.9.0-macos-x64.dmg` (Intel) | ### Windows 1. Download `Hover-Setup-3.9.0.exe` from [the release page](https://github.com/4regab/Hover/releases/tag/v3.9.0). 2. Run the installer. If you already have Hover 2.x, it installs over it in place and keeps your data. 3. Hover starts in the tray, and the island appears at the top centre of your main display. ### Linux On Debian or Ubuntu, install the `.deb` you downloaded: ```sh sudo apt install ./hover_3.9.0_amd64.deb ``` On any other distro, unpack the tarball; it holds `usr/bin/hover`, its icon and a desktop entry: ```sh sudo tar -xzf hover-3.9.0-linux-x86_64.tar.gz -C / ``` The binary carries its own fonts, icon and music. It needs only common system libraries (ALSA, fontconfig, FreeType, xkbcommon-x11, and OpenGL or Vulkan). `zenity` or `kdialog` is recommended. > **Note:** Only one copy of Hover runs at a time. Launching it again opens the running copy's dashboard. ### What works on which system | | Windows 10/11 x64 | Linux x64 (X11) | Linux on Wayland | macOS 14+ | | --- | --- | --- | --- | --- | | Notch, office, Settings | Yes | Yes | Through XWayland | Around the camera notch | | Quotas | On the notch | On the notch | On the notch | In the menu bar | | Global shortcuts | `Alt`+`N`, `Ctrl`+`Alt`+`Space` | Same | Only while an XWayland window has focus | Option-N, Control-Option-Space | | Local speech (Phonon) | Yes | Yes (arm64 not tested yet) | Yes | No: Apple's recognizer instead | | [Sandbox](https://tryhover.co/docs/sandbox.md) | No | Yes | Yes | Yes | | Agent browser, agent setup, computer use, agent desktops | No | No | No | Yes | | Desk card, helpers, pull requests, checkpoints | Yes | Yes | Yes | Yes | | Release package | Installer | .deb, tarball | .deb, tarball | Disk image (.dmg) | ### macOS Download the `.dmg` for your Mac from [the release page](https://github.com/4regab/Hover/releases/tag/v3.9.0), as described in [Hover on macOS](https://tryhover.co/docs/macos.md). You can also build `Hover.app` from source. ### The agents Hover drives the agent tools you have installed and signed in. Install at least one; see [Agents](https://tryhover.co/docs/agents.md) for what Hover looks for. ## Hover on macOS Hover 3.4 runs on a Mac. The app is written in Swift (the notch, the menu bar, Settings and voice) around the same web office and the same Rust backend as Windows and Linux. It builds on the work of Arz ([@Entourage397](https://github.com/Entourage397)), whose macOS v1.0 did the same job for Hover 2.x. > **Status:** the Mac app is new, and the project says it **hasn't been run on a Mac yet**, so treat it as a preview. If you try it, what worked and what didn't is the most useful report you can send: [open an issue](https://github.com/4regab/Hover/issues). ### Install 1. Download `Hover-3.9.0-macos-arm64.dmg` (Apple silicon) or `Hover-3.9.0-macos-x64.dmg` (Intel) from [the release page](https://github.com/4regab/Hover/releases/tag/v3.9.0). 2. Open it and drag Hover to Applications. 3. The app is signed ad hoc and **not notarized yet**, so the first time, open it with right-click → Open (or System Settings → Privacy & Security → Open Anyway). ### Build it yourself You need macOS 14 or later, Xcode's command line tools, [Rust](https://rustup.rs) and Node. From a clone of [4regab/Hover](https://github.com/4regab/Hover): ```sh xcode-select --install scripts/build-macos.sh # dist/macos-osx-arm64/Hover.app (HOVER_ARCH=x64 for Intel) open dist/macos-osx-arm64/Hover.app ``` The bundle is signed ad hoc and not notarized. It has no Dock icon: Hover is the notch and its menu bar item. Only Apple silicon is checked in CI. ### What is different on a Mac - **The notch** wraps the camera housing. A Mac without a notch gets a notch-sized pill at the top centre. Hover it, click it or press Option-N to open the office. - **Quotas are in the menu bar**, not the island: each reader you switch on shows the tool's logo in a ring of its used share, then the percentage. - **Shortcuts are fixed**: Option-N opens the office and Control-Option-Space is the voice shortcut. - **Voice uses Apple's recognizer** on the Mac, on device where the language allows. There is no Phonon, Groq or cleanup on a Mac. - **Your data** is in `~/Library/Application Support/Hover`, and the key that encrypts your history is in the login Keychain. - **Agents are found through your login shell's `PATH`**, so Homebrew, `~/.local/bin` and npm's folders work. ### Only on a Mac | Feature | What it does | | --- | --- | | **Agent setup** | A *Set up* row on each agent's page installs what is missing with the maker's own installer and opens its sign-in. Hover never sees the credentials. | | **Agent browser** | Every agent gets a browser it can open pages in, read, click and type in. You watch it in the [desk card's](https://tryhover.co/docs/desk-card.md) Browser tab. | | **Computer use** | Off until you switch it on. Agents operate other apps in the background through Cua Driver. | | **Agent desktops** | Off until you switch it on; needs macOS 26 or later on Apple silicon. Each project gets its own macOS virtual machine (a Cua Space) that its agents work in instead of your screen. Drag an app or files onto the notch to send them there. | ### Computer use Switch it on in Settings. Hover then gives every agent [Cua Driver](https://github.com/trycua/cua), and Settings installs it and asks for its two permissions, which go to CuaDriver, not to Hover. - It works in the background: input goes to the app the agent names, without moving your pointer or taking focus. - Hover's guard refuses what would get in your way: input to the whole desktop, raising or moving windows, the clipboard, and quitting apps. - Under Ask first, Ask always and Read only its calls are treated like any other tool call: asked about, or refused. - The desk card's Screen tab shows the agent's apps live. ### Permissions | Permission | Asked by | For | | --- | --- | --- | | Microphone and Speech Recognition | Hover | Voice, the first time you use the shortcut | | Screen Recording | Hover | The desk card's Screen tab (Hover must be restarted after the grant) | | Accessibility and Screen Recording | CuaDriver | Computer use | | Keychain | Hover | Its history key, and Claude Code's own sign-in for the quota if that reader is on | ### The sandbox On a Mac the [sandbox](https://tryhover.co/docs/sandbox.md) needs `srt` and `rg`: `npm install -g @anthropic-ai/sandbox-runtime@0.0.78` and `brew install ripgrep`. Without them agents start unsandboxed. ## Your first task 1. **Open the office.** Hover the island, click it, or press `Alt` + `N`. 2. **Press the circle** at the bottom left. Each agent's logo fans out; hover one to see its name. A tool that isn't installed or signed in is grey and says why. 3. **Pick an agent.** The box grows for it: prompt, image, folder, access and model. 4. **Choose a folder.** There's no prompt until a folder that exists is picked. Pick one under version control. 5. **Type the task and send.** A bot walks in, sits at a free desk and starts. ![The new task box with prompt, folder, access and model](https://tryhover.co/shots/new-task.jpg) > **Heads up:** With full tool access an agent can edit files and run commands in that folder without asking. Hover explains this the first time you open the office. To be asked first, see [Tool access](https://tryhover.co/docs/access.md). `Esc`, the chevron or a click on the office folds the box back. Your draft is kept, marked with a dot on the circle. For Kiro, the box also has a cloud button that sends the task to Kiro Web instead of running it on this computer; see [Agents](https://tryhover.co/docs/agents.md). > **Tip:** You can say the task instead of typing it. Press `Ctrl` + `Alt` + `Space`, speak, and press it again; see [Voice](https://tryhover.co/docs/voice.md). ## The notch The notch lives at the top centre of your main display. It is one borderless, always-on-top shape that never steals focus while it rests. ### At rest - **Agents at work**: their logos, what the one in front is doing (*Reading package.json*) and for how long. - **A question** an agent is waiting on, in amber, with *Deny* and *Review*. - **A finished task**: the tool's logo with a badge and the task, plus a desktop notification. - **Quotas** you switched on, each as the tool's logo in a ring. On a Mac they sit in the menu bar instead. The island's width springs to what it says, so it breathes as its words change. ### Opening and folding | To | Do | | --- | --- | | Open the office | Hover the island, click it, or press `Alt` + `N` | | Fold it | Move the pointer away, click outside, or press `Esc` with nothing open in the office | While a question waits, hovering doesn't open the office; use *Review*, which opens the question card in the notch. The only ordinary window is the **dashboard**: the same office in a normal window, opened from the tray icon or its menu. On a Mac the notch wraps the camera housing, and the shortcut is Option-N. See [Hover on macOS](https://tryhover.co/docs/macos.md). ## The Agent office Every session is a bot at its own desk. A bot's pose and bubble follow its session: waking up, thinking, reading, editing, running, waiting for you, done, couldn't finish, or stopped. - **Up to three** agents run at once, across all tools. The office keeps the newest six at desks. - **Click a bot** (or its name tag) to open its chat, or **click a desk** for its [desk card](https://tryhover.co/docs/desk-card.md). Hovering a bot or a desk says which it is. - **Helpers.** A subagent at work shows as a small bot beside its parent's desk. - **The wall board** lists the sessions as notes; **the TV** counts what's working, done, failed and stopped. - **The bookshelf** holds your history (see [Sessions & history](https://tryhover.co/docs/history.md)). - **The menu** (top right) sets the time of day, switches the lofi music on, and opens history and Settings. - **Drag** to move around, **scroll** to zoom. > **Note:** On a machine with no GPU (a virtual machine or a remote desktop) the office draws at half size and never asks for frames faster than the machine can make them. ## The desk card Click a desk in the office and a card opens at the click. It shows what the agent is doing, the question it waits on or its answer, and a reply box, so you can answer without opening the whole chat. Under it are eight tiles. Each opens a panel: | Tile | What it shows | | --- | --- | | **Terminal** | The agent's terminal | | **Files** | Search, a tree and a file view of the folder | | **Diff** | What the agent changed | | **Agents** | The agents at work on this task | | **Linked pull requests** | Pull requests linked to the work | | **Pull request** | The chat's pull request, with its checks | | **Browser** | The agent's browser (macOS only) | | **Screen** | The desktop, and live the apps the agent is using while computer use runs (on a Mac it asks for Screen Recording) | ### Pull requests The Pull request tab shows the pull request the chat opened (Hover finds it from the chat's `gh pr create` output). If there is none, it shows the current branch's, then the newest one the chat mentions. Its description is shown as Markdown. It can also set up the GitHub CLI in one click: with winget on Windows, Homebrew on a Mac, or else it shows the command to run. The sign-in shows its device code with *Copy* and *Open*. Then **Create pull request** can commit the changes, make a branch, push it and open the pull request for you. It runs `gh` and `git` on your computer and pushes to the remote you pick. ### Kiro Web chats A chat that runs in Kiro Web (see [Agents](https://tryhover.co/docs/agents.md)) has no folder on this computer, so some tabs differ. The Pull request tab works without a local repository, using the pull request the chat opened or mentions in its own repositories. The Diff tab is on: it shows that pull request's changes, or the edits the chat reported until it has one. Terminal and Files stay off. ### Helpers When an agent starts a subagent, a small bot appears beside its parent's desk, and the parent files sheets at the tray. Helpers show only what the agent actually reports. ## Approvals An agent set to ask (*Ask first* or *Ask always*, see [Tool access](https://tryhover.co/docs/access.md)) stops before the step and shows exactly what it wants: the command, or the file and its diff. There is no timeout. ![An agent asks to change a file, with Deny, Trust and Allow](https://tryhover.co/shots/approval.jpg) The question shows in three places: in the notch (amber), over the bot's head in the office, and at the end of its chat. | Answer | What happens | In the notch's card | | --- | --- | --- | | **Allow** (or Run) | Allowed once | `Enter` | | **Trust** | Hover answers the same call itself for the rest of the session | `Shift` + `Enter` | | **Deny** | Turned down; the agent carries on without it | `Esc` | Typing a reply while a question waits no longer answers it: your words are queued and the question stays up until you answer it. Stopping the run withdraws the question. ## Answers Answers show as formatted Markdown: headings, lists, tables, checklists, code, images and links. ```mermaid flowcharts are drawn as diagrams; other Mermaid kinds show as code. ![A finished answer with a table, code and a flowchart](https://tryhover.co/shots/answer.jpg) - **Code is colour-coded**, diffs carry line numbers, and command output shows the real exit code. - **Only what the agent reports.** The thinking, the subagents and the changed files in the chat are the ones the agent actually sent. Nothing is invented. - Thoughts and tool runs stay open while the agent works and fold when it is done. If you fold or unfold one yourself, Hover leaves it as you left it. - The changed files are listed under the answer, with **Copy** and **Retry**. Where Hover kept a checkpoint, **Try again** takes Retry's place. - Under an answer, **Restore** and **Try again** go back in time; see [Checkpoints](https://tryhover.co/docs/checkpoints.md). - Hover escapes everything the agent wrote and draws only its own markup, so an answer can't inject HTML or script. - Links open in your browser. Images in the session's folder load right in the answer. ### Reply, queue and pause - The composer's round button **sends**, **queues** a reply while a run goes, or **stops** the run when the box is empty. - Replies sent during a run **wait their turn**, each with its own Cancel. - **Pause** stops the answer being written now. The next queued reply starts once the agent confirms the stop. - The model pill in the composer sets the tool's default model and effort, as Settings does. ## Checkpoints Hover keeps your project folder as it was before and after every turn, so you can go back. - **Restore** (under an answer) puts the files and the chat back to just after that answer. - **Try again** (under your message) puts them back to before that message and sends it again. Both ask first, and both only work while nothing is running. The agent is told once that its folder and the chat went back. ### How it works - The copies live in a Git store of their own in Hover's data folder (`checkpoints`). Your project's own Git is never touched. - What your project's `.gitignore` leaves out is left out of the copies too. - **Git must be installed.** Without it, checkpoints are not made. - The copies are plain files, not encrypted like your sessions. Deleting a session deletes its checkpoints. > **Heads up:** Restore changes the files in your folder. Commit anything you want to keep first. ## Voice Press a shortcut, say a task, press it again. Hover shows what it heard, the folder, the agent and its access, then starts a **new chat** after a short countdown (five seconds unless you change it). > **Note:** Voice is off until you switch it on in **Settings → Voice**. Nothing is recorded or downloaded before you do. ### Setting it up 1. **Add your projects** (Settings → Projects): the folders voice may work in, and the other names you might say for them. See [Projects](https://tryhover.co/docs/projects.md). 2. **Pick how speech becomes text** (Settings → Voice), below. 3. **Optionally add cleanup.** Gemini, OpenAI or any OpenAI-compatible service, with your key and model, fixes punctuation and filler words. If it fails, the original text is used. 4. **Talk.** Press `Ctrl` + `Alt` + `Space` (you can change it; on a Mac it is Control-Option-Space and fixed) to start listening, speak, and press it again to finish. If you would rather hold the keys down, set **Settings → Voice → Voice Recording Mode** to "Hold to speak". Voice uses your **default agent**, the one last picked in the new-task circle, with that agent's own model and settings. ### Local or cloud | Mode | Where it runs | Languages | Needs | | --- | --- | --- | --- | | **Local** (Phonon) | On your computer. The recording never leaves it. | English only | Press Download on the Phonon card | | **Cloud** (Groq) | The recording is sent to Groq | Detected for you | Your own key from console.groq.com | Hover never switches between the two on its own. *Check key* tests a Groq key before you rely on it. > **Note:** On a Mac voice uses Apple's own recognizer instead, on device where the language allows. There is no Phonon, Groq or cleanup there, and macOS asks for the Microphone and Speech Recognition the first time you use the shortcut. ### What the local model needs | Platform | Download | On disk | Free space to set up | | --- | --- | --- | --- | | Windows x64 | 420 MB | 1.5 GB | 1.9 GB | | Linux x64 | 523 MB | 1.8 GB | 2.3 GB | | Linux arm64 | 410 MB | about 1.8 GB (not tested yet) | about 2.2 GB | The model itself is 164 MB. The rest is the private Python and PyTorch runtime that Phonon's engine needs; Hover keeps it in its own folder and never touches a system Python. Windows also needs the Microsoft Visual C++ Redistributable (x64), and the card says so before anything is downloaded. *Remove* deletes the whole install. ### Starting, editing, cancelling - Hover shows what it heard, the project it matched, the agent and its access, then counts down. **Settings → Voice → Start on its own** sets the wait: Off, 3, 5 (the default) or 10 seconds. - **Edit the task** to stop the countdown, then press *Start* when you're ready. - **Change the folder.** The folder pick on the card opens a list of your voice projects and the default workspace. Changing it stops the countdown, so press *Start* when you're ready. - `Esc` cancels. - **Settings → Voice → Try it** shows what would start, without starting anything. ### The aura While Hover is listening or working on what you said, the card shows only an aura: a glowing ring of light, with no words. It swirls and swells with your voice while you speak, and swirls faster with a pulse while Hover works. `Esc` still cancels. Pick its colour in **Settings → Voice → Aura colour**, by name or with any hex colour. ### Attaching screenshots Say "take a screenshot" (or "take a screenshot of this") while you speak, and Hover takes a picture of your screen and sends it with the task. You can say it as often as you like. Each one chimes, flashes the notch and says "Screenshot attached". The words themselves never reach the task. - With **Cloud** speech the picture is taken while you speak. With **Local** speech it is taken when you finish. - The preview shows the pictures, each with an × to drop it. ### Sending a task to Kiro Web Say "use Kiro Web" or "use cloud agent" (also "run in the cloud" or "in Kiro Web") and the task goes to Kiro in Kiro Web, in Kiro's cloud, instead of running on this computer. English only. - Those words are taken out of the task. - The card shows Kiro with the cloud button on, so you can switch it off before *Start*. - The card has a repository pick, with a search box: the folder's own repository, none, or a connected one. The folder pick and its default-workspace note are hidden. - Every Kiro Web task has full access, so the card has no access pick for it. See [Agents](https://tryhover.co/docs/agents.md) for what Kiro Web is. ### Dictating into a chat With a chat open and its reply box open, use the shortcut with the pointer over the chat. What you say is written into the reply instead of starting a new task. > **Heads up:** The recording is deleted once it has been turned into text. Cleanup only ever gets the text, never the audio. ## Sessions & history Sessions are kept until you delete them. Each is saved when it starts, on each reply and when a turn ends, encrypted on disk. - Open the **bookshelf** (or History in the menu) to list past sessions. - Opening one shows its chat. **Reply** and it wakes: it gets a desk back and its tool loads the conversation. - **Delete** (the bin in the chat or by a history row) asks first, stops a run, and removes the session from the office and the disk. ![Session history](https://tryhover.co/shots/history.jpg) ### Kiro Web sessions History also lists your Kiro Web sessions that were started outside Hover (in the browser, on your phone or in the terminal), by date with a "Kiro Web" mark. Click one to read the whole chat and reply. - The list is fetched each time history opens, so it follows the account you are signed in to. - If no Kiro Web sessions are listed, a row at the top of the list says why: Kiro refused the request, or it answered the same for the cloud and for this computer. - A Kiro session shows what it cost in credits, in place of its turn count. ## AI quotas Each quota is off until you switch it on in **Settings → Integrations**. Hover re-reads it five minutes after the last read finished. None of these tools has an official quota API, so Hover reads what each one exposes, read-only; if a format changes, you see a readable failure rather than a crash. | Tool | Where the number comes from | Online? | | --- | --- | --- | | Claude Code | Its usage endpoint, with Claude Code's own sign-in (never refreshed, so its tokens aren't rotated) | Yes | | Cursor | Cursor's usage summary, with the sign-in Cursor keeps on your PC | Yes | | Kiro | `kiro-cli /usage`, run on your PC | Via kiro-cli | | Codex | The newest rate limits in Codex's own session logs (`~/.codex/sessions`) | No | > **Note:** On a Mac the rings are in the menu bar, with the percentage beside each (green, amber from 70 %, red from 90 %). > **Note:** The Kiro read is the heavy one: kiro-cli and the MCP servers it starts take a few hundred MB for a few seconds, then exit. ## Keyboard | Keys | Where | Does | | --- | --- | --- | | `Alt` + `N` | Anywhere | Open or fold the office (the shortcut is configurable) | | `Ctrl` + `Alt` + `Space` | Anywhere | Press to start saying a task, press again to finish (or hold it, if Settings → Voice is set to "Hold to speak"). Configurable; off until you switch [voice](https://tryhover.co/docs/voice.md) on | | `Esc` | Office | Fold the new-task box, close the chat or panel, then fold the notch | | `Enter` | Question card | Allow | | `Shift` + `Enter` | Question card | Trust for the session | | `Esc` | Question card | Deny | | `Esc` | Voice card (listening, working or countdown) | Cancel the task | | `+` / `-` / `0` | Office | Zoom in, zoom out, reset the view | > **Note:** On a Mac the global shortcuts are Option-N and Control-Option-Space, and are fixed. > **Note:** On Linux under Wayland, the global shortcuts work only while an XWayland window has focus. ## Agents Each tool runs headlessly as a long-lived hidden process, started by the first task that needs it and shared by all of that tool's sessions. Nothing runs in a terminal, and prompts go over stdin, never on a command line. | Agent | Program Hover runs | How | | --- | --- | --- | | Codex | `codex-acp` | The `@agentclientprotocol/codex-acp` adapter | | Cursor | `cursor-agent` | `cursor-agent acp` | | OpenCode | `opencode` | `opencode serve` on 127.0.0.1 only, with a password made for each start | | Claude Code | `claude` | Its Agent SDK mode: streamed JSON over stdio, so every permission comes to Hover | | Kiro | `kiro-cli` | `kiro-cli acp` (Agent Client Protocol) | Install and sign in with each tool's own CLI. Hover checks both with the tool's status command; a tool that fails is greyed in the office with what to do. Coming soon: Gemini CLI, GitHub Copilot, Goose, Qwen Code, Cline, Amp and Junie. ### Set up on a Mac On a Mac each agent's page in Settings has a **Set up** row that installs what is missing with the maker's own installer and opens its sign-in. Hover never sees the credentials. ### Idle time After 5 or 15 idle minutes (per tool, in Settings) the process stops. Your next reply starts it again and loads the conversation back. ### Kiro An MCP server that fails to start no longer ends the task. The chat says which one didn't come up and the agent carries on. Under **Settings → Kiro**, **Continue when high usage encountered** (off by default) makes Hover send "continue" when Kiro stops because too many people are using the model. It keeps doing so until it works or you press Stop. ### Kiro Web A Kiro task can run in Kiro Web, in Kiro's cloud, instead of on this computer. Use the cloud button in the new-task box, or say it in [voice](https://tryhover.co/docs/voice.md). It is for Kiro only, on Windows and Linux. - **The repository.** The task clones the folder's own GitHub repository, another repository you have connected, or none. The repository menu has a search box. - **Access.** Every Kiro Web task has full access, so there is no access pick for it. - **Replies** reach the same session, also after a restart. The chat's cloud chip opens it in Kiro Web. - **Pictures** you paste into a Kiro Web task are sent with the prompt. - **Closing Hover or losing the connection.** Hover no longer tells Kiro to stop the task when it quits, and it saves the task's id as soon as Kiro gives it. The task carries on and picks up again when Hover is back. The project has checked this with its session tests, not yet with a live Kiro Web task. - **The chat** has a limited [desk card](https://tryhover.co/docs/desk-card.md): Pull request and Diff work, Terminal and Files are off. - **Sessions started elsewhere** are listed in [history](https://tryhover.co/docs/history.md). ### OpenCode OpenCode keeps its own providers: API keys, sign-ins, local models. Every call names the session's folder, so that folder's OpenCode config, agents, skills and MCP servers apply. It takes 30–40 s to start cold. ## Tool access Set per agent in **Settings → the agent → Tool access**, or per task in the new-task box. Projects used by voice have their own setting; see [Projects](https://tryhover.co/docs/projects.md). | Mode | The agent… | | --- | --- | | **Full** (Trust all), the default | Never asks. Edits, runs commands and goes online on its own. | | **Ask first** | Asks before commands, deletes, moves, the network, and anything outside the folder. | | **Ask always** | Asks before every change and every command. | | **Read only** | Reads and searches. Changes nothing; Hover refuses its writes. | ### Per-tool notes - **Codex**: Ask first uses its `workspace-write` mode: it asks to write outside the folder or go online, and its own sandbox decides the rest. Read only isn't offered for Codex. - **Cursor**: Hover never passes `--force`, so Cursor asks on its own; Full is Hover answering yes. Cursor's own "allow always" writes a lasting rule into `~/.cursor/cli-config.json`, which is why Hover's Trust doesn't use it. - **Trust** is Hover's, for the rest of the session. Only for Codex does Hover also pick the tool's own allow-always, since that lasts only the session too. - **Kiro Web**: every task has full access, so the new-task box and voice's card show no access pick for it. ## Sandbox On a Mac and on Linux the agents can run inside Anthropic's sandbox-runtime (`srt`). It is on by default. Each tool then: - writes only to its folders, its own state and temp; - can't read your keychains, mail or other apps' data; - opens no windows; - reaches the network only through srt's proxy, to the hosts it needs. It works alongside [tool access](https://tryhover.co/docs/access.md): access decides what an agent may ask for, the sandbox limits what it can touch. ### Setting it up Switch it off or on in Settings. If `srt` isn't installed the agents start unsandboxed, and Settings says what is missing (on a Mac it does not list the missing pieces, so check for both). | | Needs | | --- | --- | | macOS | `srt` and `rg`: `npm install -g @anthropic-ai/sandbox-runtime@0.0.78` and `brew install ripgrep` | | Linux | `srt` and bubblewrap | | Windows | Not available; the switch is off and says why | > **Note:** Any feature your system can't run is shown off with its reason beside it. ## Projects A **project** is a folder you let [voice](https://tryhover.co/docs/voice.md) work in, plus the other names you call it by. Set them up in **Settings → Projects**. | Per project | What it is for | | --- | --- | | Folder | Where the agent runs when a task names this project. | | Other names | What you actually say out loud: "the shop", "shop app", "my store". | | Tool access | What an agent may do in this folder, from the four [access modes](https://tryhover.co/docs/access.md). | > **Heads up:** A new project starts at **Ask first**. It never gets Full on its own; you have to choose that yourself. ### The default workspace When a spoken task names no project, or the name isn't clear enough to match one, the task goes to the default workspace: a folder called `Hover` in your home folder, made the first time it is needed. You can point that somewhere else, and set its access, in the same place. Projects are only used by voice. A task you type still picks its folder in the new-task box. ## Settings Open Settings from the office's menu. It sits over the office, with a back button, and your sessions keep running underneath. | Section | What's there | | --- | --- | | General | Appearance and theme, office size, and more | | Integrations | Which quotas show on the notch (the menu bar on a Mac), the [sandbox](https://tryhover.co/docs/sandbox.md), and on a Mac computer use and agent desktops | | Voice | Speech mode, microphone, shortcut, Voice Recording Mode (press to start and stop, or hold to speak), Aura colour, Groq key, the Phonon download, optional cleanup, and Try it | | Projects | The folders voice may work in, their other names, and each one's tool access | | Codex · Cursor · OpenCode · Claude Code · Kiro | Each agent's model, effort, tool access, idle time, and whether its tool steps show in the chat | An agent's **effort** choice appears once that agent has reported its effort levels, which happens after its first run. ## Themes Choose Hover light or dark, follow the system, or pick any VS Code theme on your PC: Hover finds the themes installed in VS Code, Cursor, Kiro and Windsurf. A picked theme is copied into Hover's settings, so it survives the editor being removed. The resting notch is always black, and the office keeps its own look. ## Privacy & data | | Windows | Linux | macOS | | --- | --- | --- | --- | | Data folder | `%APPDATA%\Hover` | `~/.local/share/Hover` | `~/Library/Application Support/Hover` | | Sessions | `agents/`, encrypted with AES-GCM | `agents/`, encrypted with AES-GCM | `agents/`, encrypted with AES-GCM | | API keys | `secrets.dat`, sealed with the same key, never in plain text | Same | Same | | The key | Protected by DPAPI | The Secret Service (GNOME Keyring, KWallet, KeePassXC), else a file only you can read | The login Keychain | If the key isn't available, a key you type in is kept only until Hover quits. ### What goes online There is no account, server or analytics. Hover itself goes online only for the things you switch on: - the [Cursor and Claude Code quotas](https://tryhover.co/docs/quotas.md), once every five minutes each; - the Phonon download, if you choose local speech; - Groq, if you choose cloud speech; - the cleanup service, if you add one; - Kiro Web, if you send a Kiro task there: the task runs in Kiro's cloud and clones the GitHub repository you pick; - the list of your Kiro Web sessions in [history](https://tryhover.co/docs/history.md), fetched from Kiro each time history opens. The Kiro quota runs `kiro-cli /usage` on your PC, and the Codex quota reads Codex's own logs. Neither needs Hover to go online. ### Voice data Cloud speech sends the audio to Groq. Local speech keeps recognition on your computer. Cleanup only ever gets the text, never the audio. The recording is deleted once it has been turned into text. A screenshot you ask for by voice is sent with the task to the agent you picked. ### The agents Agents run as hidden child processes in the folder you choose, in a job tied to Hover, so a quit or crash leaves none behind. OpenCode's server listens on 127.0.0.1 only, with a password made for each start. Each agent stops after 5 or 15 idle minutes and starts again when you reply. ### Checkpoints [Checkpoints](https://tryhover.co/docs/checkpoints.md) are copies of the files in your project folder (what its `.gitignore` leaves out is not copied), kept in a Git store in the data folder. Unlike sessions they are not encrypted, just as your files aren't. Deleting a session deletes its checkpoints. ### Other tools you switch on On a Mac and on Linux the [sandbox](https://tryhover.co/docs/sandbox.md) keeps agents to their folders. Computer use gives agents the right to see and operate your apps. On a Mac the agent browser talks to each agent over a Unix socket only you can use, with a token made for each start. GitHub CLI setup and Create pull request run `gh` and `git` on your computer and push to the remote you pick. > **Heads up:** The agents themselves talk to their own services, as they do outside Hover. With full access they can edit files and run commands in the folder you choose. ## Build from source Clone [4regab/Hover](https://github.com/4regab/Hover). Hover is a Rust workspace; it needs **Rust 1.89 or newer**, and the exact toolchain it is tested with is pinned in `rust-toolchain.toml`. ### Windows Install the MSVC build tools as well. ```powershell .\build.ps1 release run # build and run .\build.ps1 test # all tests .\build.ps1 publish # hoverai.exe in .\publish .\build.ps1 installer # Hover-Setup-.exe in .\dist (needs Inno Setup 6 or 7) ``` ### Linux On Ubuntu or Debian the build needs these packages (the tests also use `fonts-dejavu-core dbus gnome-keyring python3-gi`): ```sh sudo apt install build-essential pkg-config libfontconfig1-dev libfreetype-dev \ libasound2-dev libxkbcommon-dev libxkbcommon-x11-dev ``` ```sh make # release build make test sudo make install # /usr/local (PREFIX=, DESTDIR= as usual); make uninstall make package # .deb and tarball in dist/ ``` ### macOS Needs macOS 14 or later, Xcode's command line tools (`xcode-select --install`) and Node, for the office page. ```sh scripts/build-macos.sh # dist/macos-osx-arm64/Hover.app, signed ad hoc ``` `HOVER_ARCH=x64` builds for Intel. See [Hover on macOS](https://tryhover.co/docs/macos.md) for what the app does and what it asks for. ### Releases Every pull request runs the tests on Windows and Linux, and builds the Mac app on macOS. Publishing a release automatically is still being set up, so the files on a [release](https://github.com/4regab/Hover/releases) are built and attached by hand for now. > **Note:** Developer documentation lives in `docs/development` in the repo: architecture, testing, profiling and Windows notes. `AGENTS.md` summarises how the app works for people and AI agents changing it. ## How it works - **Rust and Slint.** Hover is one native app. The 2.x Windows app was .NET and WPF; 3.0 replaced it, and reads everything 2.x left behind: the data folder, the key, `settings.json` and the sessions. - **One window, one value.** The notch is a single full-size, click-through window. Its shape grows from the resting size to the office by animating one openness value; the window itself never resizes, so it never blinks. - **A Swift app on the Mac.** On macOS the notch, menu bar, Settings and voice are Swift (`macos/`), around the same web office in a WKWebView, on the Rust backend (`hover-backend`), which the app starts over JSON lines on stdin and stdout. The Slint app is for Windows and Linux. - **Never steals focus.** At rest it can't be activated, so brushing it doesn't take your keyboard. That changes only while the office is open. - **Agents over ACP.** Each tool is one hidden child speaking JSON-RPC over stdio (OpenCode: its own local HTTP server). A conversation is an ACP session; a reply goes to the same one. - **The office is drawn on the GPU**, in its own crate, at one pixel per CSS pixel. It slows right down when nothing happens and pauses while hidden. With no GPU it draws at half size instead. ## Troubleshooting **An agent is greyed out in the picker** Its tool isn't installed or signed in. The greyed logo says which; install or sign in with that tool's CLI. Status is re-checked every few minutes. **A quota shows an error** The tool changed what Hover reads. Hover shows a readable failure and keeps going; update Hover, or switch that quota off in Settings → Integrations. **OpenCode takes a while to start** Its server takes 30–40 s to start cold and around 1 GB while working. Later tasks reuse it until it idles out. **I launched Hover and nothing new appeared** Only one copy runs at a time; a second launch opens the running copy's dashboard. **The notch won't open on hover** If a question is waiting, hovering doesn't open the office. Use Review, or press `Alt` + `N`. **The voice shortcut does nothing** Check that voice is switched on in Settings → Voice. On Linux under Wayland, global shortcuts only reach Hover while an XWayland window has focus. **Local speech won't install** Phonon needs 1.9 GB free on Windows and 2.3 GB on Linux while it sets up, and on Windows the Microsoft Visual C++ Redistributable (x64). The card says so before it starts. *Remove* clears a half-finished install so you can try again. **Restore and Try again are missing or fail** Checkpoints need Git installed, and only work while no run is going. See [Checkpoints](https://tryhover.co/docs/checkpoints.md). **The sandbox is on but agents start unsandboxed** `srt` (and on a Mac `rg`) isn't installed. See [Sandbox](https://tryhover.co/docs/sandbox.md) for the commands. **The Screen tab shows only the wallpaper (Mac)** Give Hover Screen Recording with the tab's *Allow…* button, then restart Hover. **The office runs slowly in a VM or over remote desktop** With no GPU, Hover draws the office at half size and matches the frame rate the machine can manage. Making the office window smaller in Settings → General helps further. ## FAQ **Is there a Mac version?** Yes, since Hover 3.4.1: a `.dmg` for Apple silicon and one for Intel is on the release page. It isn't notarized yet, so open it the first time with right-click → Open. The Mac app is new and hasn't been run on a Mac yet by the project, so treat it as a preview. See [Hover on macOS](https://tryhover.co/docs/macos.md). **Can I undo what an agent did?** Yes. [Checkpoints](https://tryhover.co/docs/checkpoints.md) keep your folder before and after every turn. *Restore* goes back to an earlier answer and *Try again* resends a message from before it. Git must be installed. **What does it cost?** Nothing. Hover is MIT-licensed. The agents use your own plans and sign-ins. **Do I need API keys?** Not for Hover itself. Each agent uses the sign-in its own CLI keeps, and OpenCode uses its own providers. A key is needed only if you pick cloud speech or text cleanup for [voice](https://tryhover.co/docs/voice.md). **Can agents see files outside the folder?** With Full access they may. Use Ask first to be asked before anything outside the folder, or Read only. **I'm on Hover 2.x for Windows. Do I lose anything?** No. The installer replaces 2.x in place, and the native app reads the data folder, settings and sessions it left behind. **Does it work on Wayland?** Yes, through XWayland. The one limit is global shortcuts, which only reach Hover while an XWayland window has focus. Something missing or wrong? [Open an issue](https://github.com/4regab/Hover/issues).