raffi 0.25.0

A simple fuzzel launcher based on YAML file
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165

---
title: Browser Tabs
description: Search, switch to and close browser tabs from Raffi with the Vicinae browser extension
---

import { Aside } from '@astrojs/starlight/components';
import { Image } from 'astro:assets';
import browserTabsScreenshot from '../../../assets/screenshots/browser-tabs.png';
import browserTabsSetupScreenshot from '../../../assets/screenshots/browser-tabs-setup.png';

Type `tabs ` (with the trailing space) to list the tabs open in your
browsers. Tabs playing sound come first, then the ones you used most
recently. Each row shows the tab title, the site and the browser. Words
after the keyword filter by title or URL, and pasting a URL lists the tabs
of that site first.

<Image src={browserTabsScreenshot} alt="Demo browser tabs with a pinned Raffi guide selected, showing its locally stored description and logo in the preview" width={800} />

| Key        | Action                              |
|------------|-------------------------------------|
| Enter      | Switch to the tab                   |
| Ctrl+Enter | Close the tab, keeping Raffi open   |

Tabs playing sound are tagged "Playing", muted tabs "Muted", and pinned
tabs "Pinned".

<Aside type="note">
The tab list is only available in native mode. Queries typed in this mode
are not saved in the search history.
</Aside>

## Setup

Raffi gets the tabs from the browser extension made for
[Vicinae](https://docs.vicinae.com/browser-extension), so there is nothing
to build or load by hand.

1. Install the extension in your browser:
   - Chrome, Chromium, Brave, Edge, Vivaldi and other Chromium browsers:
     [Chrome Web Store](https://chromewebstore.google.com/detail/vicinae-integration/kcmipingpfbohfjckomimmahknoddnke)
   - Firefox, LibreWolf and Zen:
     [Firefox Add-ons](https://addons.mozilla.org/firefox/addon/vicinae/)
2. Register Raffi with the browsers:

   ```sh
   raffi --install-browser-host
   ```

   This writes a `com.vicinae.vicinae.json` native messaging manifest for
   every browser that has a configuration directory, and prints each file.
   Run it again if you move the `raffi` binary.
3. Restart the browser, or turn the extension off and on again. The
   extension's popup then shows it as connected.

Each running browser starts its own `raffi` process in the background,
which keeps the tab list and answers the launcher. It stops when the
browser closes.

To remove the manifests again:

```sh
raffi --uninstall-browser-host
```

Only manifests Raffi installed are removed.

### Setting up from the launcher

When no browser answers, `tabs ` lists the setup steps instead, and Enter
runs the one under the cursor:

- "Connect Raffi to your browsers" writes the manifests, as
  `--install-browser-host` does, while Raffi stays open. It shows up when
  tabs are not set up yet or the manifests point to a `raffi` binary that
  has since moved. When the browsers send their tabs to Vicinae or another
  program, the row offers to take over instead and asks for a second Enter.
- "Get the Vicinae extension for Firefox" (or Chrome, Brave, and so on)
  opens the extension's store page in that browser. Raffi offers one row per
  supported browser it finds on your machine. When a profile of that browser
  already has the extension, the row opens the browser instead.
- "Open the browser tabs setup guide" opens this page.

<Image src={browserTabsSetupScreenshot} alt="The tabs keyword offering to connect Raffi to the browsers and to open the setup guide" width={800} />

## Vicinae

The extension talks to a single program, so Raffi and Vicinae cannot both
receive the tabs. When a manifest already starts Vicinae, or anything else
Raffi did not install (a symbolic link included), `--install-browser-host`
leaves it alone and says so; add `--force` to replace it. Vicinae writes its manifest back each time it starts, so with
Vicinae running the tabs go to Vicinae.

## Site icons

Each tab shows the icon of its site. Raffi first looks in the favicon
database of the browser profile (`favicons.sqlite` for Firefox and its
forks, `Favicons` for Chromium browsers), read only and without waiting for
the browser to release it. Sites with no stored icon are downloaded in the
background once the list is shown, the same way Vicinae does, and the list
updates when they arrive. Icons are cached in `~/.cache/raffi/favicons`, and
a site with no icon is retried after a week. Tabs that are not web pages,
such as `about:` pages or `localhost`, keep the browser icon, as do sites
whose only icon is an SVG.

The download service sees the domains of your open tabs. It defaults to
twenty-icons.com; set `favicon_service` to `google` to use Google's service
instead, or to `none` to keep everything local:

```yaml
addons:
  browser_tabs:
    favicon_service: none
```

A site visited for the first time may only get its icon on a later opening,
because the browser writes new icons to its database in batches.

## Page preview

With the preview pane open (Ctrl+P), the selected tab shows the description
and image of its page, like a link preview in a chat app. For Firefox and
its forks Raffi reads them from the browser history first. Otherwise, once
the selection rests on a tab, Raffi fetches the page itself and reads its
`og:description` and `og:image` tags. That request carries none of your
browser cookies, so a page behind a login shows what it shows logged out.
Fetched details are cached for a day in `~/.cache/raffi/previews`, and
images are kept there until they go a week without being shown.

Only pages on named hosts that resolve to public addresses are fetched,
redirects included, never addresses such as `192.168.1.1` or names on your
local network. Images are scaled down when saved, and SVG images are not
shown. With `favicon_service: none` nothing is downloaded: tabs show
only what Firefox stored, without its image.

## Switching windows

The extension switches the tab and asks the browser to bring its window
forward, but on Wayland compositors usually ignore that request. On
Hyprland, niri and sway, Raffi then focuses the browser window showing the
tab itself, waiting up to a second for the window title to follow. In other
sessions the tab is switched inside the browser and the window stays where
it is.

To open the list from a key binding, pass the keyword as the initial query:

```sh
raffi -u native -i "tabs "
```

## In the main list

To find tabs without typing `tabs` first, add `browser_tabs` to
[`general.main_view`](../../configuration/general-settings/#main-view). Typing
`gmail` then lists the matching tabs next to your launchers.

## Configuration

```yaml
addons:
  browser_tabs:
    trigger: "t"
```

See the [addon reference](../../reference/addon-configuration/#browser-tabs) for
every field.