> ## Documentation Index
> Fetch the complete documentation index at: https://docs.otter-shell.org/llms.txt
> Use this file to discover all available pages before exploring further.

# otter-overview

> Workspace and window overlay with cards, thumbnails, search, and an application grid.

`otter-overview` is a one-shot overlay. Bind it to a hotkey. Workspace cards, window thumbnails, search, and an app grid. Click a tile to jump there. Type to launch an app. Escape closes.

It sits on `zwlr_layer_shell_v1` overlay, on the output under the cursor. It is not a compositor.

Niri has its own overview. That one uses [otter-wallpaper](/desktop/otter-wallpaper) `overview_enabled` for a blurred backdrop. `otter-overview` is a separate app.

## Usage

```bash theme={null}
otter-overview
```

Typical Hyprland bind:

```ini theme={null}
bind = SUPER, Super_L, exec, otter-overview
```

Do not autostart it. Same pattern as [otter-launcher](/desktop/otter-launcher): run on a hotkey, it exits when you dismiss.

## What you can do

* Click a window tile to focus it. The overlay closes first so it cannot steal focus back.
* Click a workspace card to switch to it.
* Drag a tile onto another card to move that window. Drag onto another tile in the same card to swap them. Drop on empty space snaps back.
* Hover a tile and click the close chip to close that window.
* Click the search bar, or just type, for the application grid. Enter launches. Escape clears search, then closes.
* Wheel or trackpad scrolls the card strip, or pages the app grid. Page Up / Page Down and the `< n / m >` chips change pages. Arrows and Tab move between tiles or app cells.

Only that output's workspaces show.

If tiled windows sit past the output edge (Hyprland scrolling layout, niri columns, mango scrolling tags), the card becomes a sideways lane. Wheel pans that lane. A niri floating window stays on the card instead of joining the lane.

## Configuration

Config: `~/.config/otter-shell/otter-overview.conf` (fallback: `/etc/otter-shell/otter-overview.conf`). Created on first run.

<Tip>
  The **Overview** tab in [otter-settings](/desktop/otter-settings) writes the same file.
</Tip>

```conf theme={null}
axis = vertical
card_scale_percent = 50
card_gap = 24
close_button_size = 34
search_width = 420
capture_windows = true
max_capture_px = 1280
capture_refresh_ms = 4000
empty_workspaces = one_empty
```

| Key                  | Meaning                                                                                                                                           |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `axis`               | `vertical` or `horizontal` card strip                                                                                                             |
| `card_scale_percent` | Card size as a percent of the output, clamped 20 to 80. Default 50.                                                                               |
| `empty_workspaces`   | `all` (every compositor workspace), `one_empty` (occupied plus one spare; a new slot appears when that one fills), or `populated` (occupied only) |
| `capture_windows`    | Grab window thumbnails when the compositor supports it                                                                                            |
| `max_capture_px`     | Longest side of a stored capture, clamped 768 to 2048                                                                                             |
| `capture_refresh_ms` | Thumbnail refresh interval. `0` disables. Other values clamp to 1000 to 30000                                                                     |

Omit color keys (`overlay_color`, `card_color`, `card_active_color`, `card_border_color`, `tile_color`, `search_color`, `text_color`, `muted_color`, `accent_color`) to inherit from [theme.conf](/configuration/themes). `font_path`, `font_size`, and `border_radius` are optional the same way.

## Thumbnails

Startup captures every window before the first paint, active workspace first. If capture is missing, tiles use a stable per-app tint.

Hyprland can also use `hyprland_toplevel_export`. Other compositors use `ext-image-copy-capture` when present.

## Compositor support

| Compositor | Workspaces and windows                                                | Thumbnails                              |
| ---------- | --------------------------------------------------------------------- | --------------------------------------- |
| Hyprland   | IPC (`j/workspaces`, `j/clients`, `j/monitors`)                       | `hyprland_toplevel_export`              |
| niri       | IPC (`Workspaces`, `Windows`, `FocusWindow`, `MoveWindowToWorkspace`) | `ext-image-copy-capture` when available |
| mango/dwl  | `zdwl_ipc_output_v2` + wlr-foreign-toplevel (tag cards; no otter-tag) | `ext-image-copy-capture` when available |
| Other      | `ext-workspace` + wlr-foreign-toplevel fallback                       | `ext-image-copy-capture` when available |

Needs `zwlr_layer_shell_v1`.

## Keyboard

| Key                 | Action                          |
| ------------------- | ------------------------------- |
| Escape              | Clear search, then close        |
| Enter               | Launch selected app             |
| Arrows / Tab        | Move between tiles or app cells |
| Page Up / Page Down | Change app-grid pages           |

## Dependencies

* Wayland compositor with `zwlr_layer_shell_v1`
* Window thumbnails need a capture protocol (`ext_image_copy_capture` or Hyprland export)