1# Dumber, fully unfeatured unbloated browser for tiling WMs
2
3<p align="center">
4  <img src="assets/logo.svg" alt="Dumber Logo" width="256" height="256" />
5</p>
6
7
8https://github.com/user-attachments/assets/394f5f7e-a475-42da-b483-5a58b2ea2f51
9
10
11
12A dumb browser that works like your favorite terminal multiplexer.
13
14## Features
15- **Wayland native**: No X11/XWayland dependency, works with Sway, Hyprland, River, Niri, etc.
16- **Tabs and workspaces**: Each tab holds a workspace with split or stacked panes.
17- **Keyboard-driven**: Keyboard workflow inspired by Zellij.
18- **Smart popup handling**: OAuth flows, window.open(), and popup deduplication for tiling WMs.
19- **GPU rendering**: Hardware video acceleration with automatic VA-API/VDPAU detection.
20- **Built-in ad blocking**: UBlock-based network + cosmetic filtering.
21- **Launcher integration**: dmenu-style with rofi/fuzzel support, shows favicons and history.
22- **Search shortcuts**: Quick search via bangs (e.g., `!g golang` for Google, `!gi cats` for Google Images).
23- **Customizable themes**: Light and dark palettes with semantic color tokens.
24- **Persistent storage**: SQLite for history, favorites, per-domain zoom levels, and sessions.
25- **Live configuration**: Single config file with hot reload when possible.
26- **Session management**: Zellij-style session save/restore with automatic snapshots and resurrection.
27
28## Status
29Dumber is almost feature-complete. Next steps will focus on stability, performance, and bug fixing.
30
31Core features work well for daily use but expect some rough edges. Some features are still alpha/experimental (notably consume-or-expel panes) and may change behavior between releases.
32
33## Quick Start
34
35```bash
36# Download and install
37wget https://github.com/bnema/dumber/releases/latest/download/dumber_linux_x86_64.tar.gz
38tar -xzf dumber_linux_x86_64.tar.gz
39mkdir -p ~/.local/bin && install -m 755 dumber_*/dumber ~/.local/bin/
40
41# Run
42dumber browse https://example.com
43```
44
45See [Install](#install) for AUR, Flatpak, building from source, and runtime dependencies.
46
47## Controls & Shortcuts
48
49### Keyboard Shortcuts
50
51#### Browser Controls
52| Shortcut | Action | Notes |
53|----------|--------|-------|
54| **F12** | Open Developer Tools | WebKit inspector |
55| **Ctrl+L** | Open Omnibox | URL/search input with history |
56| **Ctrl+F** | Find in Page | Search text within current page |
57| **Ctrl+=** | Zoom In | Firefox-compatible zoom levels |
58| **Ctrl++** | Zoom In | Alternative plus key |
59| **Ctrl+-** | Zoom Out | Works across keyboard layouts |
60| **Ctrl+0** | Reset Zoom | Return to 100% zoom |
61| **Ctrl+Shift+C** | Copy URL | Copy current URL to clipboard with toast |
62| **Ctrl+Shift+P** | Print Page | Open native print dialog |
63| **Ctrl+R** / **F5** | Reload Page | Refresh current page |
64| **Ctrl+Shift+R** | Hard Reload | Refresh ignoring cache |
65| **Ctrl+←** / **Ctrl+→** | Navigate Back/Forward | Browser history navigation |
66
67#### Tab Management
68| Shortcut | Action | Notes |
69|----------|--------|-------|
70| **Ctrl+T** | Enter Tab Mode | Modal mode for tab operations |
71| **Ctrl+Tab** | Next Tab | Quick tab switching |
72| **Ctrl+Shift+Tab** | Previous Tab | Quick tab switching |
73| **Ctrl+W** | Close Tab | Close current tab |
74| **N** / **C** (in tab mode) | New Tab | Create new tab |
75| **X** (in tab mode) | Close Tab | Close current tab |
76| **L** / **Tab** (in tab mode) | Next Tab | Navigate to next tab |
77| **H** / **Shift+Tab** (in tab mode) | Previous Tab | Navigate to previous tab |
78| **Escape** (in tab mode) | Exit Tab Mode | Return to normal navigation |
79
80#### Pane Management
81| Shortcut | Action | Notes |
82|----------|--------|-------|
83| **Ctrl+P** | Enter Pane Mode | Modal mode for pane operations |
84| **→** / **R** (in pane mode) | Split Right | Create new pane to the right |
85| **←** / **L** (in pane mode) | Split Left | Create new pane to the left |
86| **↑** / **U** (in pane mode) | Split Up | Create new pane above |
87| **↓** / **D** (in pane mode) | Split Down | Create new pane below |
88| **S** (in pane mode) | Stack Pane | Create stacked pane (Zellij-style) |
89| **X** (in pane mode) | Close Pane | Close current pane |
90| **m** (in pane mode) | Move Pane To Tab | Opens a tab picker modal |
91| **M** (in pane mode) | Move Pane To Next Tab | Moves to the next tab, creates new tab if needed |
92| **Enter** (in pane mode) | Confirm Action | Confirm pane operation |
93| **Escape** (in pane mode) | Exit Pane Mode | Return to normal navigation |
94| **Alt+Arrow Keys** | Navigate Panes | Move focus between panes |
95| **Alt+Up/Down** | Navigate Stack | Navigate between stacked panes |
96| **Alt+[** / **Alt+]** | Consume / Expel Pane | Experimental (alpha): merge into sibling stack, or expel out of stack |
97| **Alt+Shift+[** / **Alt+Shift+]** | Consume / Expel Pane (Vertical) | Experimental (alpha): up/down variants |
98
99#### Resize Mode
100| Shortcut | Action | Notes |
101|----------|--------|-------|
102| **Ctrl+N** | Enter Resize Mode | Modal mode for pane resizing |
103| **←/↓/↑/→** / **h/j/k/l** (in resize mode) | Move Divider | Resizes the nearest split by moving the divider |
104| **H/J/K/L** (in resize mode) | Move Divider (Inverse) | Inverts the direction |
105| **+ / -** (in resize mode) | Smart Resize | Grow/shrink the active pane (best-effort) |
106| **Enter** (in resize mode) | Confirm | Exit resize mode |
107| **Escape** (in resize mode) | Cancel | Exit resize mode |
108
109#### Session Management
110| Shortcut | Action | Notes |
111|----------|--------|-------|
112| **Ctrl+O** | Enter Session Mode | Modal mode for session operations |
113| **Ctrl+Shift+S** | Open Session Manager | Direct access to session browser |
114| **S** / **W** (in session mode) | Open Session Manager | Browse and restore sessions |
115| **Escape** (in session mode) | Exit Session Mode | Return to normal navigation |
116
117### Mouse Controls
118| Action | Result | Notes |
119|--------|---------|-------|
120| **Drag pane divider** | Resize panes | Updates split ratio and persists in session snapshots |
121| **Ctrl+Scroll Up** | Zoom In | Smooth zoom control |
122| **Ctrl+Scroll Down** | Zoom Out | Smooth zoom control |
123| **Mouse Button 8** | Navigate Back | Side button (back) |
124| **Mouse Button 9** | Navigate Forward | Side button (forward) |
125| **Two-finger Swipe** | Back/Forward | When supported by touchpad |
126
127### Omnibox/Find Mode (when active)
128| Shortcut | Action | Notes |
129|----------|--------|-------|
130| **Escape** | Close/Clear | Clear input if text present, close if empty |
131| **Enter** | Execute/Navigate | Navigate to URL or jump to match |
132| **Shift+Enter** | Previous Match | Find mode: go to previous match |
133| **Alt+Enter** | Center Match | Find mode: center on match, keep open |
134| **Tab** | Toggle View | Omnibox mode: switch between history and favorites |
135| **Space** | Toggle Favorite | Omnibox mode: favorite/unfavorite selected item |
136| **Ctrl+1-9, 0** | Quick Navigate | Jump to result by number (1-10) |
137| **↑/↓ Arrow** | Navigate Results | Browse suggestions/matches |
138| **Hold key 400ms** | Accent Picker | Shows accented variants in any text input (e.g., hold 'e' for è, é, ê, ë) |
139
140All zoom changes are automatically persisted per-domain and restored on next visit.
141
142## Install
143
144### Pre-built Binaries (Recommended)
145
146Pre-built binaries are available for Linux (x86_64/amd64) in the [releases page](https://github.com/bnema/dumber/releases). See [Quick Start](#quick-start) for installation instructions.
147
148### Arch Linux (AUR)
149
150Dumber is available on the [Arch User Repository (AUR)](https://aur.archlinux.org/packages?K=dumber-browser):
151
152```bash
153# Binary package (pre-built, recommended - fastest install)
154yay -S dumber-browser-bin
155
156# Or build from source (latest git - bleeding edge)
157yay -S dumber-browser-git
158```
159
160Both packages install to `/usr/bin/dumber` and include desktop integration. The binary package downloads pre-built releases from GitHub, while the git package builds from the latest source code.
161
162> **Note:** When installed via AUR, the self-updater is automatically disabled. Use `yay -Syu` or your preferred AUR helper to update.
163
164### Flatpak
165
166A Flatpak bundle is available in each release. This is the easiest way to install Dumber with all dependencies included:
167
168```bash
169# Download the Flatpak bundle from the latest release
170wget https://github.com/bnema/dumber/releases/latest/download/dumber.flatpak
171
172# Install it (user-level, no root required)
173flatpak install --user dumber.flatpak
174
175# Run it
176flatpak run dev.bnema.Dumber browse
177```
178
179To uninstall:
180```bash
181flatpak uninstall --user dev.bnema.Dumber
182```
183
184### Dependencies
185
186Required for both pre-built binaries and source builds:
187
188**Arch Linux:**
189```bash
190# Core WebKitGTK 6.0 and GTK4
191sudo pacman -S webkitgtk-6.0 gtk4
192
193# GStreamer for media playback
194sudo pacman -S gst-plugins-base gst-plugins-good gst-plugins-bad gst-plugins-ugly gst-libav gst-plugin-pipewire pipewire pipewire-pulse
195
196# Hardware video decoding (required for YouTube, Twitch, etc.)
197sudo pacman -S gst-plugin-va
198
199# VA-API drivers (choose based on your GPU)
200# AMD: sudo pacman -S mesa
201# NVIDIA: sudo pacman -S libva-nvidia-driver
202# Intel: sudo pacman -S libva-intel-driver intel-media-driver
203```
204
205**Debian/Ubuntu:**
206
207> ⚠️ **Note:** Ubuntu 24.04 LTS ships with GLib 2.80, but this project requires GLib 2.84+ due to newer GTK/WebKitGTK runtime requirements. Use Arch Linux, Fedora 41+, or another distribution with recent GLib packages.
208
209```bash
210# Core WebKitGTK and GTK4
211sudo apt install libwebkitgtk-6.0-4 libgtk-4-1
212
213# GStreamer for media playback
214sudo apt install gstreamer1.0-tools gstreamer1.0-plugins-base gstreamer1.0-plugins-good gstreamer1.0-plugins-bad gstreamer1.0-plugins-ugly gstreamer1.0-libav gstreamer1.0-pipewire
215
216# Hardware video decoding (gst-plugins-bad includes VA stateless decoders)
217# VA-API drivers
218sudo apt install va-driver-all
219```
220
221### Build From Source
222
223**Note**: `go install` will not work for this project because the frontend assets must be built first and embedded into the binary.
224
225**Prerequisites:**
226- Go 1.25+
227- Node.js 20+ and npm (for building the embedded TypeScript frontend)
228- WebKitGTK 6 and GTK4 dev packages:
229  - Minimum runtime versions: WebKitGTK 6.0 >= `2.50`, GTK4 >= `4.20`, GLib >= `2.84`
230  - Debian/Ubuntu: `libwebkitgtk-6.0-dev libgtk-4-dev build-essential`
231  - Arch: `webkitgtk-6.0 gtk4 base-devel`
232  - Verify your system with: `dumber doctor` (or configure `runtime.prefix` for `/opt` installs)
233
234**Build options:**
235- GUI build (default, recommended):
236  - Clone the repo and run `make build` (builds frontend first, then Go with GUI support)
237  - The resulting `./dist/dumber` binary includes the native GUI window
238- CLI‑only (no native window):
239  - Clone the repo and run `make build-no-gui`
240  - The resulting `./dist/dumber-no-gui` binary runs CLI flows with GUI code stubbed
241
242## Usage
243- Open a URL, local file, or search:
244  - `dumber browse https://example.com`
245  - `dumber browse example.com`         # scheme auto‑added
246  - `dumber browse ./test.html`         # local file path (converted to file://)
247  - `dumber browse dumb://home`         # built-in home page (stats, shortcuts, etc.)
248  - `dumber browse "!g golang"`        # search via bang shortcut
249- Show version information:
250  - `dumber about`                      # version, commit, and build date
251- Check for and install updates:
252  - `dumber update`                     # check and install if available
253  - `dumber update --force`             # force reinstall (skips version check)
254- Launcher integration (dmenu‑style examples with favicon support):
255  - rofi:   `dumber dmenu | rofi -dmenu -show-icons -p "🔍 " | dumber dmenu --select`
256  - fuzzel: `dumber dmenu | fuzzel --dmenu -p "🔍 " | dumber dmenu --select`
257  - `dumber dmenu --interactive`        # built-in TUI fuzzy finder
258  - `dumber dmenu --days 7`             # show history from last 7 days (default: 30)
259  - `dumber dmenu --most-visited`       # sort by visit count instead of recency
260- Manage browsing history:
261  - `dumber history`                    # interactive history browser (timeline tabs + fuzzy search)
262  - `dumber history --json`             # output recent entries as JSON
263  - `dumber history --json --max 50`    # limit JSON output to N entries
264  - `dumber history stats`              # show history statistics
265  - `dumber history clear`              # interactive time-range cleanup
266- Clean up data:
267  - `dumber purge`                      # interactive selection (TUI)
268  - `dumber purge --force`              # remove everything (no prompts)
269- Manage configuration:
270  - `dumber config status`              # show config path and migration availability
271  - `dumber config migrate`             # add missing default settings to config
272  - `dumber config migrate --yes`       # skip confirmation prompt
273- Manage sessions:
274  - `dumber sessions`                   # interactive session browser (TUI)
275  - `dumber sessions list`              # list saved sessions
276  - `dumber sessions list --json`       # output sessions as JSON
277  - `dumber sessions list --limit 50`   # limit number of sessions shown
278  - `dumber sessions restore <id>`      # restore a session in a new window
279  - `dumber sessions delete <id>`       # delete a saved session
280- Manage logs:
281  - `dumber logs`                       # list sessions with log files
282  - `dumber logs <session>`             # show logs for a session (full ID or unique suffix)
283  - `dumber logs -f <session>`          # follow logs in real time
284  - `dumber logs -n 200 <session>`      # show last N lines
285  - `dumber logs clear`                 # clean up old log files
286  - `dumber logs clear --all`           # remove all log files
287- Generate documentation:
288  - `dumber gen-docs`                   # install man pages to ~/.local/share/man/man1/
289  - `dumber gen-docs --format markdown` # generate markdown docs to ./docs/
290  - `dumber gen-docs --output ./man`    # generate to custom directory
291
292### Dmenu mode invocation
293You can invoke dmenu mode in two ways:
294- Piped launcher (generate options): `dumber dmenu`
295- Receive selection from stdin: `dumber dmenu --select`
296
297For a built-in fuzzy finder UI, use: `dumber dmenu --interactive`
298
299In GUI mode the app serves an embedded home page via `dumb://home`, and frontend assets under `dumb://app/...`.
300
301There is also a WIP config UI at `dumb://config` for viewing/applying settings with live reload.
302
303## Tab Management
304
305Each tab holds its own workspace. Each workspace can contain multiple panes (split or stacked). Switch between tabs to switch between independent workspaces.
306
307### How it Works
3081. **Enter Tab Mode**: Press `Ctrl+T` to enter tab mode (modal interface with timeout)
3092. **Create/Close Tabs**: Use keyboard shortcuts:
310   - `N` or `C` - New tab
311   - `X` - Close current tab
3123. **Navigate**: Use `Ctrl+Tab` / `Ctrl+Shift+Tab` for quick tab switching, or `L`/`H` in tab mode
3134. **Exit**: Press `Escape` to exit tab mode or wait for timeout
314
315
316
317## Pane Management
318
319Split your browser window into multiple panes, each running independent web sessions.
320
321### How it Works
3221. **Enter Pane Mode**: Press `Ctrl+P` to enter pane mode (modal interface with timeout)
3232. **Split or Stack Panes**: Use arrow keys or letter shortcuts:
324   - `→` or `R` - Split right
325   - `←` or `L` - Split left
326   - `↑` or `U` - Split up
327   - `↓` or `D` - Split down
328   - `S` - Stack panes (Zellij-style, shows title bars for collapsed panes)
3293. **Navigate**: Use `Alt+Arrow Keys` to move focus between split panes, or `Alt+Up/Down` to navigate within stacked panes
3304. **Close**: Press `X` in pane mode to close the current pane
331
332## Session Management
333
334Dumber automatically saves your browser session (tabs, panes, split ratios, URLs) and allows you to restore previous sessions.
335
336### How it Works
3371. **Automatic Snapshots**: Session state is saved automatically (debounced, every 5s by default) and on graceful shutdown
3382. **Session Manager**: Press `Ctrl+O → s` or `Ctrl+Shift+S` to open the session manager modal
3393. **Browse Sessions**: View active and exited sessions with tab/pane previews
3404. **Restore**: Select an exited session to restore it in a new browser window
3415. **CLI Access**: Use `dumber sessions` for an interactive TUI, or `dumber sessions list/restore/delete` for scripting
342
343
344
345## Configuration
346
347Configuration file: `~/.config/dumber/config.toml` (supports TOML, JSON, YAML)
348
349A default config is created on first run. Changes are applied automatically (hot reload). Override any setting with `DUMB_BROWSER_*` or `DUMBER_*` environment variables.
350
351**Full documentation**: [docs/CONFIG.md](docs/CONFIG.md) - Complete reference for all settings, workspace controls, shortcuts, styling, and more.
352
353
354## Development
355
356Dumber uses pure-Go bindings (no CGO) but requires GTK4/WebKitGTK runtime libraries for the GUI.
357
358### Environment
359
360Set `ENV=dev` to use a local `.dev/dumber/` directory for config, data, state, and cache instead of XDG paths. Useful for testing without affecting your real browser data.
361
362### Make Targets
363
364| Target | Description |
365|--------|-------------|
366| `make build` | Build frontend + binary (recommended) |
367| `make build-quick` | Build binary only (faster for backend work) |
368| `make build-frontend` | Build webui pages (homepage, error, config) |
369| `make dev` | Run with `go run` |
370| `make test` | Run tests |
371| `make test-race` | Run tests with race detection |
372| `make test-cover` | Run tests with coverage report |
373| `make lint` | Run golangci-lint |
374| `make lint-fix` | Run golangci-lint with auto-fix |
375| `make fmt` | Format Go code |
376| `make generate` | Generate SQLC code |
377| `make mocks` | Generate mock implementations |
378| `make install-tools` | Install dev tools (sqlc, golangci-lint) |
379| `make check` | Verify tools, build, and tests work |
380| `make clean` | Remove build artifacts |
381
382### Flatpak
383
384| Target | Description |
385|--------|-------------|
386| `make flatpak-deps` | Install Flatpak build dependencies |
387| `make flatpak-build` | Build Flatpak bundle |
388| `make flatpak-install` | Install Flatpak locally for testing |
389| `make flatpak-run` | Run the installed Flatpak |
390| `make flatpak-clean` | Clean Flatpak build artifacts |
391
392### Release
393
394| Target | Description |
395|--------|-------------|
396| `make release-snapshot` | Build snapshot with goreleaser |
397| `make release` | Create full release with goreleaser |
398
399## Media (GStreamer) & Hardware Acceleration
400
401WebKitGTK uses GStreamer for media playback. Dumber includes automatic hardware video acceleration support that detects your GPU and configures the appropriate drivers.
402
403**Hardware Acceleration Features:**
404- Automatic GPU detection (AMD, NVIDIA, Intel)
405- VA-API and VDPAU driver configuration
406- Support for H.264, HEVC, VP9, and AV1 codecs
407- Significantly reduced CPU usage during video streaming
408
409**Required packages:**
410- Arch Linux:
411  - `sudo pacman -S gst-plugins-base gst-plugins-good gst-plugins-bad gst-plugins-ugly gst-libav gst-plugin-pipewire pipewire pipewire-pulse`
412  - Hardware decoding: `gst-plugin-va` (stateless VA decoders - required for WebKitGTK)
413  - VA-API drivers: `mesa` (AMD), `libva-nvidia-driver` (NVIDIA), `libva-intel-driver intel-media-driver` (Intel)
414- Debian/Ubuntu:
415  - `sudo apt install gstreamer1.0-tools gstreamer1.0-plugins-base gstreamer1.0-plugins-good gstreamer1.0-plugins-bad gstreamer1.0-plugins-ugly gstreamer1.0-libav gstreamer1.0-pipewire`
416  - Hardware decoding: `gstreamer1.0-plugins-bad` includes VA stateless decoders
417  - VA-API drivers: `va-driver-all` (covers most GPUs)
418
419## References
420- puregotk: https://github.com/jwijenbergh/puregotk
421- puregotk-webkit: https://github.com/bnema/puregotk-webkit
422- ublock-webkit-filters (filter list releases): https://github.com/bnema/ublock-webkit-filters
423
424## Contribute
425I will gladly accept contributions, especially related to UI/UX enhancements. Feel free to open an issue and let's discuss it!
426
427## License
428This project is licensed under the MIT License. See `LICENSE` for details.