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
129All zoom changes are automatically persisted per-domain and restored on next visit.
130
131## Quick Start
132
133**Option 1: Use Pre-built Binaries (Recommended)**
134
135Download the latest release from the [releases page](https://github.com/bnema/dumber/releases):
136```bash
137# Download latest release
138wget https://github.com/bnema/dumber/releases/latest/download/dumber_linux_x86_64.tar.gz
139
140# Extract and install to ~/.local/bin (enables auto-updates)
141tar -xzf dumber_linux_x86_64.tar.gz
142mkdir -p ~/.local/bin
143install -m 755 dumber_*/dumber ~/.local/bin/
144
145# Ensure ~/.local/bin is in your PATH (add to ~/.bashrc or ~/.zshrc if needed)
146# export PATH="$HOME/.local/bin:$PATH"
147```
148
149Then install runtime dependencies (see [Dependencies](#dependencies) section below).
150
151**Option 2: Build From Source**
152
153Prerequisites:
154- Go 1.25+
155- Node.js 20+ and npm (for building the embedded TypeScript frontend)
156- For GUI build: WebKitGTK 6 and GTK4 dev packages (examples)
157  - Minimum runtime versions: WebKitGTK 6.0 >= `2.50`, GTK4 >= `4.20`, GLib >= `2.84`
158  - Debian/Ubuntu: `libwebkitgtk-6.0-dev libgtk-4-dev build-essential`
159  - Arch: `webkitgtk-6.0 gtk4 base-devel`
160  - Verify your system with: `dumber doctor` (or configure `runtime.prefix` for `/opt` installs)
161
162Build options:
163- Default (recommended):
164  - `make build`          # builds frontend + Go (pure Go; CGO off)
165  - Run: `./dist/dumber`  # run the app
166- Quick (no frontend rebuild):
167  - `make build-quick`
168  - Run: `./dist/dumber`
169
170Development:
171- `make dev` runs `go run ./cmd/dumber`
172- `make test` runs tests; `make lint` runs golangci‑lint
173
174## Install
175
176### Pre-built Binaries (Recommended)
177
178Pre-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.
179
180### Dependencies
181
182Required for both pre-built binaries and source builds:
183
184**Arch Linux:**
185```bash
186# Core WebKitGTK 6.0 and GTK4
187sudo pacman -S webkitgtk-6.0 gtk4
188
189# GStreamer for media playback
190sudo pacman -S gst-plugins-base gst-plugins-good gst-plugins-bad gst-plugins-ugly gst-libav gst-plugin-pipewire pipewire pipewire-pulse
191
192# Hardware video decoding (required for YouTube, Twitch, etc.)
193sudo pacman -S gst-plugin-va
194
195# VA-API drivers (choose based on your GPU)
196# AMD: sudo pacman -S libva-mesa-driver mesa
197# NVIDIA: sudo pacman -S libva-nvidia-driver
198# Intel: sudo pacman -S libva-intel-driver intel-media-driver
199```
200
201**Debian/Ubuntu:**
202
203> ⚠️ **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.
204
205```bash
206# Core WebKitGTK and GTK4
207sudo apt install libwebkitgtk-6.0-4 libgtk-4-1
208
209# GStreamer for media playback
210sudo 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
211
212# Hardware video decoding (gst-plugins-bad includes VA stateless decoders)
213# VA-API drivers
214sudo apt install va-driver-all
215```
216
217### Build From Source
218
219**Note**: `go install` will not work for this project because the frontend assets must be built first and embedded into the binary.
220
221**Prerequisites:**
222- Go 1.25+
223- Node.js 20+ and npm (for building the embedded TypeScript frontend)
224- WebKitGTK 6 and GTK4 dev packages:
225  - Minimum runtime versions: WebKitGTK 6.0 >= `2.50`, GTK4 >= `4.20`, GLib >= `2.84`
226  - Debian/Ubuntu: `libwebkitgtk-6.0-dev libgtk-4-dev build-essential`
227  - Arch: `webkitgtk-6.0 gtk4 base-devel`
228  - Verify your system with: `dumber doctor` (or configure `runtime.prefix` for `/opt` installs)
229
230**Build options:**
231- GUI build (default, recommended):
232  - Clone the repo and run `make build` (builds frontend first, then Go with GUI support)
233  - The resulting `./dist/dumber` binary includes the native GUI window
234- CLI‑only (no native window):
235  - Clone the repo and run `make build-no-gui`
236  - The resulting `./dist/dumber-no-gui` binary runs CLI flows with GUI code stubbed
237
238## Usage
239- Open a URL, local file, or search:
240  - `dumber browse https://example.com`
241  - `dumber browse example.com`         # scheme auto‑added
242  - `dumber browse ./test.html`         # local file path (converted to file://)
243  - `dumber browse dumb://home`         # built-in home page (stats, shortcuts, etc.)
244  - `dumber browse "!g golang"`        # search via bang shortcut
245- Show version information:
246  - `dumber about`                      # version, commit, and build date
247- Check for and install updates:
248  - `dumber update`                     # check and install if available
249  - `dumber update --force`             # force reinstall (skips version check)
250- Launcher integration (dmenu‑style examples with favicon support):
251  - rofi:   `dumber dmenu | rofi -dmenu -show-icons -p "🔍 " | dumber dmenu --select`
252  - fuzzel: `dumber dmenu | fuzzel --dmenu -p "🔍 " | dumber dmenu --select`
253  - `dumber dmenu --interactive`        # built-in TUI fuzzy finder
254  - `dumber dmenu --max 200`            # limit output entries
255- Manage browsing history:
256  - `dumber history`                    # interactive history browser (timeline tabs + fuzzy search)
257  - `dumber history --json`             # output recent entries as JSON
258  - `dumber history --json --max 50`    # limit JSON output to N entries
259  - `dumber history stats`              # show history statistics
260  - `dumber history clear`              # interactive time-range cleanup
261- Clean up data:
262  - `dumber purge`                      # interactive selection (TUI)
263  - `dumber purge --force`              # remove everything (no prompts)
264- Manage configuration:
265  - `dumber config status`              # show config path and migration availability
266  - `dumber config migrate`             # add missing default settings to config
267  - `dumber config migrate --yes`       # skip confirmation prompt
268- Manage sessions:
269  - `dumber sessions`                   # interactive session browser (TUI)
270  - `dumber sessions list`              # list saved sessions
271  - `dumber sessions list --json`       # output sessions as JSON
272  - `dumber sessions list --limit 50`   # limit number of sessions shown
273  - `dumber sessions restore <id>`      # restore a session in a new window
274  - `dumber sessions delete <id>`       # delete a saved session
275- Manage logs:
276  - `dumber logs`                       # list sessions with log files
277  - `dumber logs <session>`             # show logs for a session (full ID or unique suffix)
278  - `dumber logs -f <session>`          # follow logs in real time
279  - `dumber logs -n 200 <session>`      # show last N lines
280  - `dumber logs clear`                 # clean up old log files
281  - `dumber logs clear --all`           # remove all log files
282- Generate documentation:
283  - `dumber gen-docs`                   # install man pages to ~/.local/share/man/man1/
284  - `dumber gen-docs --format markdown` # generate markdown docs to ./docs/
285  - `dumber gen-docs --output ./man`    # generate to custom directory
286
287### Dmenu mode invocation
288You can invoke dmenu mode in two ways:
289- Piped launcher (generate options): `dumber dmenu`
290- Receive selection from stdin: `dumber dmenu --select`
291
292For a built-in fuzzy finder UI, use: `dumber dmenu --interactive`
293
294In GUI mode the app serves an embedded home page via `dumb://home`, and frontend assets under `dumb://app/...`.
295
296There is also a WIP config UI at `dumb://config` for viewing/applying settings with live reload.
297
298## Tab Management
299
300Each tab holds its own workspace. Each workspace can contain multiple panes (split or stacked). Switch between tabs to switch between independent workspaces.
301
302### How it Works
3031. **Enter Tab Mode**: Press `Ctrl+T` to enter tab mode (modal interface with timeout)
3042. **Create/Close Tabs**: Use keyboard shortcuts:
305   - `N` or `C` - New tab
306   - `X` - Close current tab
3073. **Navigate**: Use `Ctrl+Tab` / `Ctrl+Shift+Tab` for quick tab switching, or `L`/`H` in tab mode
3084. **Exit**: Press `Escape` to exit tab mode or wait for timeout
309
310
311
312## Pane Management
313
314Split your browser window into multiple panes, each running independent web sessions.
315
316### How it Works
3171. **Enter Pane Mode**: Press `Ctrl+P` to enter pane mode (modal interface with timeout)
3182. **Split or Stack Panes**: Use arrow keys or letter shortcuts:
319   - `→` or `R` - Split right
320   - `←` or `L` - Split left
321   - `↑` or `U` - Split up
322   - `↓` or `D` - Split down
323   - `S` - Stack panes (Zellij-style, shows title bars for collapsed panes)
3243. **Navigate**: Use `Alt+Arrow Keys` to move focus between split panes, or `Alt+Up/Down` to navigate within stacked panes
3254. **Close**: Press `X` in pane mode to close the current pane
326
327## Session Management
328
329Dumber automatically saves your browser session (tabs, panes, split ratios, URLs) and allows you to restore previous sessions.
330
331### How it Works
3321. **Automatic Snapshots**: Session state is saved automatically (debounced, every 5s by default) and on graceful shutdown
3332. **Session Manager**: Press `Ctrl+O → s` or `Ctrl+Shift+S` to open the session manager modal
3343. **Browse Sessions**: View active and exited sessions with tab/pane previews
3354. **Restore**: Select an exited session to restore it in a new browser window
3365. **CLI Access**: Use `dumber sessions` for an interactive TUI, or `dumber sessions list/restore/delete` for scripting
337
338
339
340## Configuration
341
342Configuration file: `~/.config/dumber/config.toml` (supports TOML, JSON, YAML)
343
344A default config is created on first run. Changes are applied automatically (hot reload). Override any setting with `DUMB_BROWSER_*` or `DUMBER_*` environment variables.
345
346**Full documentation**: [docs/CONFIG.md](docs/CONFIG.md) - Complete reference for all settings, workspace controls, shortcuts, styling, and more.
347
348
349## Building With WebKitGTK 6 (GTK4)
350- Dumber uses pure-Go bindings (no CGO).
351- You still need the system GTK4/WebKitGTK runtime libraries installed to run the GUI.
352- Build targets:
353  - `make build` (builds frontend + binary)
354  - `make build-quick` (binary only; skips frontend build)
355
356## Media (GStreamer) & Hardware Acceleration
357
358WebKitGTK uses GStreamer for media playback. Dumber includes automatic hardware video acceleration support that detects your GPU and configures the appropriate drivers.
359
360**Hardware Acceleration Features:**
361- Automatic GPU detection (AMD, NVIDIA, Intel)
362- VA-API and VDPAU driver configuration
363- Support for H.264, HEVC, VP9, and AV1 codecs
364- Significantly reduced CPU usage during video streaming
365
366**Required packages:**
367- Arch Linux:
368  - `sudo pacman -S gst-plugins-base gst-plugins-good gst-plugins-bad gst-plugins-ugly gst-libav gst-plugin-pipewire pipewire pipewire-pulse`
369  - Hardware decoding: `gst-plugin-va` (stateless VA decoders - required for WebKitGTK)
370  - VA-API drivers: `libva-mesa-driver mesa` (AMD), `libva-nvidia-driver` (NVIDIA), `libva-intel-driver intel-media-driver` (Intel)
371- Debian/Ubuntu:
372  - `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`
373  - Hardware decoding: `gstreamer1.0-plugins-bad` includes VA stateless decoders
374  - VA-API drivers: `va-driver-all` (covers most GPUs)
375
376## References
377- puregotk: https://github.com/jwijenbergh/puregotk
378- puregotk-webkit: https://github.com/bnema/puregotk-webkit
379- ublock-webkit-filters (filter list releases): https://github.com/bnema/ublock-webkit-filters
380
381## Contribute
382I will gladly accept contributions, especially related to UI/UX enhancements. Feel free to open an issue and let's discuss it!
383
384## License
385This project is licensed under the MIT License. See `LICENSE` for details.