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
27## Status
28Dumber recently completed a full rewrite in pure Go using the `puregotk` and `puregotk-webkit` libraries.
29
30The project is now structured around clean architecture, which makes it much easier to iterate on features and improve testability.
31
32Early development with regular releases. Core features work well for daily use but expect some rough edges.
33
34## Controls & Shortcuts
35
36### Keyboard Shortcuts
37
38#### Browser Controls
39| Shortcut | Action | Notes |
40|----------|--------|-------|
41| **F12** | Open Developer Tools | WebKit inspector |
42| **Ctrl+L** | Open Omnibox | URL/search input with history |
43| **Ctrl+F** | Find in Page | Search text within current page |
44| **Ctrl+=** | Zoom In | Firefox-compatible zoom levels |
45| **Ctrl++** | Zoom In | Alternative plus key |
46| **Ctrl+-** | Zoom Out | Works across keyboard layouts |
47| **Ctrl+0** | Reset Zoom | Return to 100% zoom |
48| **Ctrl+Shift+C** | Copy URL | Copy current URL to clipboard with toast |
49| **Ctrl+Shift+P** | Print Page | Open native print dialog |
50| **Ctrl+R** / **F5** | Reload Page | Refresh current page |
51| **Ctrl+Shift+R** | Hard Reload | Refresh ignoring cache |
52| **Ctrl+←** / **Ctrl+→** | Navigate Back/Forward | Browser history navigation |
53
54#### Tab Management
55| Shortcut | Action | Notes |
56|----------|--------|-------|
57| **Ctrl+T** | Enter Tab Mode | Modal mode for tab operations |
58| **Ctrl+Tab** | Next Tab | Quick tab switching |
59| **Ctrl+Shift+Tab** | Previous Tab | Quick tab switching |
60| **Ctrl+W** | Close Tab | Close current tab |
61| **N** / **C** (in tab mode) | New Tab | Create new tab |
62| **X** (in tab mode) | Close Tab | Close current tab |
63| **L** / **Tab** (in tab mode) | Next Tab | Navigate to next tab |
64| **H** / **Shift+Tab** (in tab mode) | Previous Tab | Navigate to previous tab |
65| **Escape** (in tab mode) | Exit Tab Mode | Return to normal navigation |
66
67#### Pane Management
68| Shortcut | Action | Notes |
69|----------|--------|-------|
70| **Ctrl+P** | Enter Pane Mode | Modal mode for pane operations |
71| **→** / **R** (in pane mode) | Split Right | Create new pane to the right |
72| **←** / **L** (in pane mode) | Split Left | Create new pane to the left |
73| **↑** / **U** (in pane mode) | Split Up | Create new pane above |
74| **↓** / **D** (in pane mode) | Split Down | Create new pane below |
75| **S** (in pane mode) | Stack Pane | Create stacked pane (Zellij-style) |
76| **X** (in pane mode) | Close Pane | Close current pane |
77| **Enter** (in pane mode) | Confirm Action | Confirm pane operation |
78| **Escape** (in pane mode) | Exit Pane Mode | Return to normal navigation |
79| **Alt+Arrow Keys** | Navigate Panes | Move focus between panes |
80| **Alt+Up/Down** | Navigate Stack | Navigate between stacked panes |
81
82### Mouse Controls
83| Action | Result | Notes |
84|--------|---------|-------|
85| **Ctrl+Scroll Up** | Zoom In | Smooth zoom control |
86| **Ctrl+Scroll Down** | Zoom Out | Smooth zoom control |
87| **Mouse Button 8** | Navigate Back | Side button (back) |
88| **Mouse Button 9** | Navigate Forward | Side button (forward) |
89| **Two-finger Swipe** | Back/Forward | When supported by touchpad |
90
91### Omnibox/Find Mode (when active)
92| Shortcut | Action | Notes |
93|----------|--------|-------|
94| **Escape** | Close/Clear | Clear input if text present, close if empty |
95| **Enter** | Execute/Navigate | Navigate to URL or jump to match |
96| **Shift+Enter** | Previous Match | Find mode: go to previous match |
97| **Alt+Enter** | Center Match | Find mode: center on match, keep open |
98| **Tab** | Toggle View | Omnibox mode: switch between history and favorites |
99| **Space** | Toggle Favorite | Omnibox mode: favorite/unfavorite selected item |
100| **Ctrl+1-9, 0** | Quick Navigate | Jump to result by number (1-10) |
101| **↑/↓ Arrow** | Navigate Results | Browse suggestions/matches |
102
103All zoom changes are automatically persisted per-domain and restored on next visit.
104
105## Quick Start
106
107**Option 1: Use Pre-built Binaries (Recommended)**
108
109Download the latest release from the [releases page](https://github.com/bnema/dumber/releases):
110```bash
111wget https://github.com/bnema/dumber/releases/latest/download/dumber_<version>_linux_x86_64.tar.gz
112tar -xzf dumber_<version>_linux_x86_64.tar.gz
113sudo install -m 755 dumber /usr/local/bin/
114```
115
116Then install runtime dependencies (see [Install](#install) section for details).
117
118**Option 2: Build From Source**
119
120Prerequisites:
121- Go 1.25+
122- Node.js 20+ and npm (for building the embedded TypeScript frontend)
123- For GUI build: WebKitGTK 6 and GTK4 dev packages (examples)
124  - Minimum runtime versions: WebKitGTK 6.0 >= `2.50`, GTK4 >= `4.20`, GLib >= `2.84`
125  - Debian/Ubuntu: `libwebkitgtk-6.0-dev libgtk-4-dev build-essential`
126  - Arch: `webkitgtk-6.0 gtk4 base-devel`
127  - Verify your system with: `dumber doctor` (or configure `runtime.prefix` for `/opt` installs)
128
129Build options:
130- Default (recommended):
131  - `make build`          # builds frontend + Go (pure Go; CGO off)
132  - Run: `./dist/dumber`  # run the app
133- Quick (no frontend rebuild):
134  - `make build-quick`
135  - Run: `./dist/dumber`
136
137Development:
138- `make dev` runs `go run ./cmd/dumber`
139- `make test` runs tests; `make lint` runs golangci‑lint
140
141## Install
142
143### Pre-built Binaries (Recommended)
144
145Pre-built binaries are available for Linux (x86_64/amd64) in the [releases page](https://github.com/bnema/dumber/releases). These include all frontend assets and are ready to use:
146
147```bash
148# Download and install latest release
149wget https://github.com/bnema/dumber/releases/latest/download/dumber_<version>_linux_x86_64.tar.gz
150tar -xzf dumber_<version>_linux_x86_64.tar.gz
151sudo install -m 755 dumber /usr/local/bin/
152```
153
154Replace `<version>` with the desired version (e.g., `0.14.1`), or use the direct link from the releases page.
155
156**Dependencies** (required for both pre-built binaries and source builds):
157
158**Arch Linux:**
159```bash
160# Core WebKitGTK 6.0 and GTK4
161sudo pacman -S webkitgtk-6.0 gtk4
162
163# GStreamer for media playback
164sudo pacman -S gst-plugins-base gst-plugins-good gst-plugins-bad gst-plugins-ugly gst-libav gst-plugin-pipewire pipewire pipewire-pulse
165
166# Hardware video decoding (required for YouTube, Twitch, etc.)
167sudo pacman -S gst-plugin-va
168
169# VA-API drivers (choose based on your GPU)
170# AMD: sudo pacman -S libva-mesa-driver mesa
171# NVIDIA: sudo pacman -S libva-nvidia-driver
172# Intel: sudo pacman -S libva-intel-driver intel-media-driver
173```
174
175**Debian/Ubuntu:**
176
177> ⚠️ **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.
178
179```bash
180# Core WebKitGTK and GTK4
181sudo apt install libwebkitgtk-6.0-4 libgtk-4-1
182
183# GStreamer for media playback
184sudo 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
185
186# Hardware video decoding (gst-plugins-bad includes VA stateless decoders)
187# VA-API drivers
188sudo apt install va-driver-all
189```
190
191### Build From Source
192
193**Note**: `go install` will not work for this project because the frontend assets must be built first and embedded into the binary.
194
195**Prerequisites:**
196- Go 1.25+
197- Node.js 20+ and npm (for building the embedded TypeScript frontend)
198- WebKitGTK 6 and GTK4 dev packages:
199  - Minimum runtime versions: WebKitGTK 6.0 >= `2.50`, GTK4 >= `4.20`, GLib >= `2.84`
200  - Debian/Ubuntu: `libwebkitgtk-6.0-dev libgtk-4-dev build-essential`
201  - Arch: `webkitgtk-6.0 gtk4 base-devel`
202  - Verify your system with: `dumber doctor` (or configure `runtime.prefix` for `/opt` installs)
203
204**Build options:**
205- GUI build (default, recommended):
206  - Clone the repo and run `make build` (builds frontend first, then Go with GUI support)
207  - The resulting `./dist/dumber` binary includes the native GUI window
208- CLI‑only (no native window):
209  - Clone the repo and run `make build-no-gui`
210  - The resulting `./dist/dumber-no-gui` binary runs CLI flows with GUI code stubbed
211
212## Usage
213- Open a URL or search:
214  - `dumber browse https://example.com`
215  - `dumber browse example.com`        # scheme auto‑added
216  - `dumber browse dumb://home`        # built-in home page (stats, shortcuts, etc.)
217  - `dumber browse "!g golang"`         # Google search via bang shortcut
218- Show version information:
219  - `dumber about`                     # display version, commit, and build date
220- Launcher integration (dmenu‑style examples with favicon support):
221  - rofi:   `dumber dmenu | rofi -dmenu -show-icons -p "🔍 " | dumber dmenu --select`
222  - fuzzel: `dumber dmenu | fuzzel --dmenu -p "🔍 " | dumber dmenu --select`
223- Manage browsing history:
224  - `dumber history`                  # interactive history browser (timeline tabs + fuzzy search)
225  - `dumber history --json`           # output recent entries as JSON
226  - `dumber history --json --max 50`  # limit JSON output to N entries
227  - `dumber history stats`            # show history statistics
228  - `dumber history clear`            # interactive cleanup (select time range)
229- Clean up data and cache:
230  - `dumber purge`                        # purge all data (with confirmation)
231  - `dumber purge --force`                # purge all data (no confirmation)
232  - `dumber purge -d -H -c`               # purge database and both caches
233  - `dumber purge --browser-data`         # purge WebKit data (cookies, etc.)
234- Manage logs:
235  - `dumber logs list`                    # list available log files
236  - `dumber logs tail`                    # tail current log file
237  - `dumber logs clean`                   # clean up old log files
238
239### Dmenu mode invocation
240You can invoke dmenu mode in two ways:
241- Subcommand (recommended): `dumber dmenu` … and `dumber dmenu --select`
242- Root flag (generate options only): `dumber --dmenu`
243
244Note: The root flag path only generates options; for processing a selection (`--select`), use the `dmenu` subcommand as the receiving command.
245
246In GUI mode the app serves an embedded home page via `dumb://home`, and frontend assets under `dumb://app/...`.
247
248There is also a WIP config UI at `dumb://config` for viewing/applying settings with live reload.
249
250## Tab Management
251
252Each tab holds its own workspace. Each workspace can contain multiple panes (split or stacked). Switch between tabs to switch between independent workspaces.
253
254### How it Works
2551. **Enter Tab Mode**: Press `Ctrl+T` to enter tab mode (modal interface with timeout)
2562. **Create/Close Tabs**: Use keyboard shortcuts:
257   - `N` or `C` - New tab
258   - `X` - Close current tab
2593. **Navigate**: Use `Ctrl+Tab` / `Ctrl+Shift+Tab` for quick tab switching, or `L`/`H` in tab mode
2604. **Exit**: Press `Escape` to exit tab mode or wait for timeout
261
262Tab mode provides visual feedback with an orange border indicator.
263
264## Pane Management
265
266Split your browser window into multiple panes, each running independent web sessions.
267
268### How it Works
2691. **Enter Pane Mode**: Press `Ctrl+P` to enter pane mode (modal interface with timeout)
2702. **Split or Stack Panes**: Use arrow keys or letter shortcuts:
271   - `→` or `R` - Split right
272   - `←` or `L` - Split left
273   - `↑` or `U` - Split up
274   - `↓` or `D` - Split down
275   - `S` - Stack panes (Zellij-style, shows title bars for collapsed panes)
2763. **Navigate**: Use `Alt+Arrow Keys` to move focus between split panes, or `Alt+Up/Down` to navigate within stacked panes
2774. **Close**: Press `X` in pane mode to close the current pane
278
279## Configuration
280
281Configuration file: `~/.config/dumber/config.toml` (supports TOML, JSON, YAML)
282
283A default config is created on first run. Changes are applied automatically (hot reload). Override any setting with `DUMB_BROWSER_*` or `DUMBER_*` environment variables.
284
285**Full documentation**: [docs/CONFIG.md](docs/CONFIG.md) - Complete reference for all settings, workspace controls, shortcuts, styling, and more.
286
287
288## Building With WebKitGTK 6 (GTK4)
289- Dumber uses pure-Go bindings (no CGO).
290- You still need the system GTK4/WebKitGTK runtime libraries installed to run the GUI.
291- Build targets:
292  - `make build` (builds frontend + binary)
293  - `make build-quick` (binary only; skips frontend build)
294
295## Media (GStreamer) & Hardware Acceleration
296
297WebKitGTK uses GStreamer for media playback. Dumber includes automatic hardware video acceleration support that detects your GPU and configures the appropriate drivers.
298
299**Hardware Acceleration Features:**
300- Automatic GPU detection (AMD, NVIDIA, Intel)
301- VA-API and VDPAU driver configuration
302- Support for H.264, HEVC, VP9, and AV1 codecs
303- Significantly reduced CPU usage during video streaming
304
305**Required packages:**
306- Arch Linux:
307  - `sudo pacman -S gst-plugins-base gst-plugins-good gst-plugins-bad gst-plugins-ugly gst-libav gst-plugin-pipewire pipewire pipewire-pulse`
308  - Hardware decoding: `gst-plugin-va` (stateless VA decoders - required for WebKitGTK)
309  - VA-API drivers: `libva-mesa-driver mesa` (AMD), `libva-nvidia-driver` (NVIDIA), `libva-intel-driver intel-media-driver` (Intel)
310- Debian/Ubuntu:
311  - `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`
312  - Hardware decoding: `gstreamer1.0-plugins-bad` includes VA stateless decoders
313  - VA-API drivers: `va-driver-all` (covers most GPUs)
314
315## References
316- puregotk: https://github.com/jwijenbergh/puregotk
317- puregotk-webkit: https://github.com/bnema/puregotk-webkit
318- ublock-webkit-filters (filter list releases): https://github.com/bnema/ublock-webkit-filters
319
320## Contribute
321I will gladly accept contributions, especially related to UI/UX enhancements. Feel free to open an issue and let's discuss it!
322
323## License
324This project is licensed under the MIT License. See `LICENSE` for details.