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| **Enter** (in pane mode) | Confirm Action | Confirm pane operation |
81| **Escape** (in pane mode) | Exit Pane Mode | Return to normal navigation |
82| **Alt+Arrow Keys** | Navigate Panes | Move focus between panes |
83| **Alt+Up/Down** | Navigate Stack | Navigate between stacked panes |
84| **Alt+[** / **Alt+]** | Consume / Expel Pane | Experimental (alpha): merge into sibling stack, or expel out of stack |
85| **Alt+Shift+[** / **Alt+Shift+]** | Consume / Expel Pane (Vertical) | Experimental (alpha): up/down variants |
86
87#### Resize Mode
88| Shortcut | Action | Notes |
89|----------|--------|-------|
90| **Ctrl+N** | Enter Resize Mode | Modal mode for pane resizing |
91| **←/↓/↑/→** / **h/j/k/l** (in resize mode) | Move Divider | Resizes the nearest split by moving the divider |
92| **H/J/K/L** (in resize mode) | Move Divider (Inverse) | Inverts the direction |
93| **+ / -** (in resize mode) | Smart Resize | Grow/shrink the active pane (best-effort) |
94| **Enter** (in resize mode) | Confirm | Exit resize mode |
95| **Escape** (in resize mode) | Cancel | Exit resize mode |
96
97#### Session Management
98| Shortcut | Action | Notes |
99|----------|--------|-------|
100| **Ctrl+O** | Enter Session Mode | Modal mode for session operations |
101| **Ctrl+Shift+S** | Open Session Manager | Direct access to session browser |
102| **S** / **W** (in session mode) | Open Session Manager | Browse and restore sessions |
103| **Escape** (in session mode) | Exit Session Mode | Return to normal navigation |
104
105### Mouse Controls
106| Action | Result | Notes |
107|--------|---------|-------|
108| **Drag pane divider** | Resize panes | Updates split ratio and persists in session snapshots |
109| **Ctrl+Scroll Up** | Zoom In | Smooth zoom control |
110| **Ctrl+Scroll Down** | Zoom Out | Smooth zoom control |
111| **Mouse Button 8** | Navigate Back | Side button (back) |
112| **Mouse Button 9** | Navigate Forward | Side button (forward) |
113| **Two-finger Swipe** | Back/Forward | When supported by touchpad |
114
115### Omnibox/Find Mode (when active)
116| Shortcut | Action | Notes |
117|----------|--------|-------|
118| **Escape** | Close/Clear | Clear input if text present, close if empty |
119| **Enter** | Execute/Navigate | Navigate to URL or jump to match |
120| **Shift+Enter** | Previous Match | Find mode: go to previous match |
121| **Alt+Enter** | Center Match | Find mode: center on match, keep open |
122| **Tab** | Toggle View | Omnibox mode: switch between history and favorites |
123| **Space** | Toggle Favorite | Omnibox mode: favorite/unfavorite selected item |
124| **Ctrl+1-9, 0** | Quick Navigate | Jump to result by number (1-10) |
125| **↑/↓ Arrow** | Navigate Results | Browse suggestions/matches |
126
127All zoom changes are automatically persisted per-domain and restored on next visit.
128
129## Quick Start
130
131**Option 1: Use Pre-built Binaries (Recommended)**
132
133Download the latest release from the [releases page](https://github.com/bnema/dumber/releases):
134```bash
135# Download latest release
136wget https://github.com/bnema/dumber/releases/latest/download/dumber_linux_x86_64.tar.gz
137
138# Extract and install to ~/.local/bin (enables auto-updates)
139tar -xzf dumber_linux_x86_64.tar.gz
140mkdir -p ~/.local/bin
141install -m 755 dumber_*/dumber ~/.local/bin/
142
143# Ensure ~/.local/bin is in your PATH (add to ~/.bashrc or ~/.zshrc if needed)
144# export PATH="$HOME/.local/bin:$PATH"
145```
146
147Then install runtime dependencies (see [Dependencies](#dependencies) section below).
148
149**Option 2: Build From Source**
150
151Prerequisites:
152- Go 1.25+
153- Node.js 20+ and npm (for building the embedded TypeScript frontend)
154- For GUI build: WebKitGTK 6 and GTK4 dev packages (examples)
155  - Minimum runtime versions: WebKitGTK 6.0 >= `2.50`, GTK4 >= `4.20`, GLib >= `2.84`
156  - Debian/Ubuntu: `libwebkitgtk-6.0-dev libgtk-4-dev build-essential`
157  - Arch: `webkitgtk-6.0 gtk4 base-devel`
158  - Verify your system with: `dumber doctor` (or configure `runtime.prefix` for `/opt` installs)
159
160Build options:
161- Default (recommended):
162  - `make build`          # builds frontend + Go (pure Go; CGO off)
163  - Run: `./dist/dumber`  # run the app
164- Quick (no frontend rebuild):
165  - `make build-quick`
166  - Run: `./dist/dumber`
167
168Development:
169- `make dev` runs `go run ./cmd/dumber`
170- `make test` runs tests; `make lint` runs golangci‑lint
171
172## Install
173
174### Pre-built Binaries (Recommended)
175
176Pre-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.
177
178### Dependencies
179
180Required for both pre-built binaries and source builds:
181
182**Arch Linux:**
183```bash
184# Core WebKitGTK 6.0 and GTK4
185sudo pacman -S webkitgtk-6.0 gtk4
186
187# GStreamer for media playback
188sudo pacman -S gst-plugins-base gst-plugins-good gst-plugins-bad gst-plugins-ugly gst-libav gst-plugin-pipewire pipewire pipewire-pulse
189
190# Hardware video decoding (required for YouTube, Twitch, etc.)
191sudo pacman -S gst-plugin-va
192
193# VA-API drivers (choose based on your GPU)
194# AMD: sudo pacman -S libva-mesa-driver mesa
195# NVIDIA: sudo pacman -S libva-nvidia-driver
196# Intel: sudo pacman -S libva-intel-driver intel-media-driver
197```
198
199**Debian/Ubuntu:**
200
201> ⚠️ **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.
202
203```bash
204# Core WebKitGTK and GTK4
205sudo apt install libwebkitgtk-6.0-4 libgtk-4-1
206
207# GStreamer for media playback
208sudo 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
209
210# Hardware video decoding (gst-plugins-bad includes VA stateless decoders)
211# VA-API drivers
212sudo apt install va-driver-all
213```
214
215### Build From Source
216
217**Note**: `go install` will not work for this project because the frontend assets must be built first and embedded into the binary.
218
219**Prerequisites:**
220- Go 1.25+
221- Node.js 20+ and npm (for building the embedded TypeScript frontend)
222- WebKitGTK 6 and GTK4 dev packages:
223  - Minimum runtime versions: WebKitGTK 6.0 >= `2.50`, GTK4 >= `4.20`, GLib >= `2.84`
224  - Debian/Ubuntu: `libwebkitgtk-6.0-dev libgtk-4-dev build-essential`
225  - Arch: `webkitgtk-6.0 gtk4 base-devel`
226  - Verify your system with: `dumber doctor` (or configure `runtime.prefix` for `/opt` installs)
227
228**Build options:**
229- GUI build (default, recommended):
230  - Clone the repo and run `make build` (builds frontend first, then Go with GUI support)
231  - The resulting `./dist/dumber` binary includes the native GUI window
232- CLI‑only (no native window):
233  - Clone the repo and run `make build-no-gui`
234  - The resulting `./dist/dumber-no-gui` binary runs CLI flows with GUI code stubbed
235
236## Usage
237- Open a URL or search:
238  - `dumber browse https://example.com`
239  - `dumber browse example.com`        # scheme auto‑added
240  - `dumber browse dumb://home`        # built-in home page (stats, shortcuts, etc.)
241  - `dumber browse "!g golang"`         # Google search via bang shortcut
242- Show version information:
243  - `dumber about`                     # display version, commit, and build date
244- Launcher integration (dmenu‑style examples with favicon support):
245  - rofi:   `dumber dmenu | rofi -dmenu -show-icons -p "🔍 " | dumber dmenu --select`
246  - fuzzel: `dumber dmenu | fuzzel --dmenu -p "🔍 " | dumber dmenu --select`
247- Manage browsing history:
248  - `dumber history`                  # interactive history browser (timeline tabs + fuzzy search)
249  - `dumber history --json`           # output recent entries as JSON
250  - `dumber history --json --max 50`  # limit JSON output to N entries
251  - `dumber history stats`            # show history statistics
252  - `dumber history clear`            # interactive cleanup (select time range)
253- Clean up data and cache:
254  - `dumber purge`                        # purge all data (with confirmation)
255  - `dumber purge --force`                # purge all data (no confirmation)
256  - `dumber purge -d -H -c`               # purge database and both caches
257  - `dumber purge --browser-data`         # purge WebKit data (cookies, etc.)
258- Manage sessions:
259  - `dumber sessions`                     # interactive session browser (TUI)
260  - `dumber sessions list`                # list saved sessions
261  - `dumber sessions list --json`         # output sessions as JSON
262  - `dumber sessions restore <id>`        # restore a session in new window
263  - `dumber sessions delete <id>`         # delete a saved session
264- Manage logs:
265  - `dumber logs list`                    # list available log files
266  - `dumber logs tail`                    # tail current log file
267  - `dumber logs clean`                   # clean up old log files
268
269### Dmenu mode invocation
270You can invoke dmenu mode in two ways:
271- Subcommand (recommended): `dumber dmenu` … and `dumber dmenu --select`
272- Root flag (generate options only): `dumber --dmenu`
273
274Note: The root flag path only generates options; for processing a selection (`--select`), use the `dmenu` subcommand as the receiving command.
275
276In GUI mode the app serves an embedded home page via `dumb://home`, and frontend assets under `dumb://app/...`.
277
278There is also a WIP config UI at `dumb://config` for viewing/applying settings with live reload.
279
280## Tab Management
281
282Each tab holds its own workspace. Each workspace can contain multiple panes (split or stacked). Switch between tabs to switch between independent workspaces.
283
284### How it Works
2851. **Enter Tab Mode**: Press `Ctrl+T` to enter tab mode (modal interface with timeout)
2862. **Create/Close Tabs**: Use keyboard shortcuts:
287   - `N` or `C` - New tab
288   - `X` - Close current tab
2893. **Navigate**: Use `Ctrl+Tab` / `Ctrl+Shift+Tab` for quick tab switching, or `L`/`H` in tab mode
2904. **Exit**: Press `Escape` to exit tab mode or wait for timeout
291
292Tab mode provides visual feedback with an orange border indicator.
293
294## Pane Management
295
296Split your browser window into multiple panes, each running independent web sessions.
297
298### How it Works
2991. **Enter Pane Mode**: Press `Ctrl+P` to enter pane mode (modal interface with timeout)
3002. **Split or Stack Panes**: Use arrow keys or letter shortcuts:
301   - `→` or `R` - Split right
302   - `←` or `L` - Split left
303   - `↑` or `U` - Split up
304   - `↓` or `D` - Split down
305   - `S` - Stack panes (Zellij-style, shows title bars for collapsed panes)
3063. **Navigate**: Use `Alt+Arrow Keys` to move focus between split panes, or `Alt+Up/Down` to navigate within stacked panes
3074. **Close**: Press `X` in pane mode to close the current pane
308
309## Session Management
310
311Dumber automatically saves your browser session (tabs, panes, split ratios, URLs) and allows you to restore previous sessions.
312
313### How it Works
3141. **Automatic Snapshots**: Session state is saved automatically (debounced, every 5s by default) and on graceful shutdown
3152. **Session Manager**: Press `Ctrl+O → s` or `Ctrl+Shift+S` to open the session manager modal
3163. **Browse Sessions**: View active and exited sessions with tab/pane previews
3174. **Restore**: Select an exited session to restore it in a new browser window
3185. **CLI Access**: Use `dumber sessions` for an interactive TUI, or `dumber sessions list/restore/delete` for scripting
319
320Session mode provides visual feedback with a purple border indicator.
321
322## Configuration
323
324Configuration file: `~/.config/dumber/config.toml` (supports TOML, JSON, YAML)
325
326A default config is created on first run. Changes are applied automatically (hot reload). Override any setting with `DUMB_BROWSER_*` or `DUMBER_*` environment variables.
327
328**Full documentation**: [docs/CONFIG.md](docs/CONFIG.md) - Complete reference for all settings, workspace controls, shortcuts, styling, and more.
329
330
331## Building With WebKitGTK 6 (GTK4)
332- Dumber uses pure-Go bindings (no CGO).
333- You still need the system GTK4/WebKitGTK runtime libraries installed to run the GUI.
334- Build targets:
335  - `make build` (builds frontend + binary)
336  - `make build-quick` (binary only; skips frontend build)
337
338## Media (GStreamer) & Hardware Acceleration
339
340WebKitGTK uses GStreamer for media playback. Dumber includes automatic hardware video acceleration support that detects your GPU and configures the appropriate drivers.
341
342**Hardware Acceleration Features:**
343- Automatic GPU detection (AMD, NVIDIA, Intel)
344- VA-API and VDPAU driver configuration
345- Support for H.264, HEVC, VP9, and AV1 codecs
346- Significantly reduced CPU usage during video streaming
347
348**Required packages:**
349- Arch Linux:
350  - `sudo pacman -S gst-plugins-base gst-plugins-good gst-plugins-bad gst-plugins-ugly gst-libav gst-plugin-pipewire pipewire pipewire-pulse`
351  - Hardware decoding: `gst-plugin-va` (stateless VA decoders - required for WebKitGTK)
352  - VA-API drivers: `libva-mesa-driver mesa` (AMD), `libva-nvidia-driver` (NVIDIA), `libva-intel-driver intel-media-driver` (Intel)
353- Debian/Ubuntu:
354  - `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`
355  - Hardware decoding: `gstreamer1.0-plugins-bad` includes VA stateless decoders
356  - VA-API drivers: `va-driver-all` (covers most GPUs)
357
358## References
359- puregotk: https://github.com/jwijenbergh/puregotk
360- puregotk-webkit: https://github.com/bnema/puregotk-webkit
361- ublock-webkit-filters (filter list releases): https://github.com/bnema/ublock-webkit-filters
362
363## Contribute
364I will gladly accept contributions, especially related to UI/UX enhancements. Feel free to open an issue and let's discuss it!
365
366## License
367This project is licensed under the MIT License. See `LICENSE` for details.