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