1# Dumber
2
3[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![Go Report Card](https://goreportcard.com/badge/github.com/bnema/dumber)](https://goreportcard.com/report/github.com/bnema/dumber)
4
5Dumber is a keyboard-driven web browser, built around panes, workspaces, and modal controls.
6
7Tabs contain workspaces. Workspaces contain panes. Panes can be split, stacked, moved, resized, and closed from the keyboard.
8
9The layout model is inspired by terminal multiplexers such as Zellij and tmux, but applied to web browsing this is particularly suited for Wayland compositors such as Niri or Hyprland.
10
11[Website](https://dumber.bnema.dev) · [Documentation](https://dumber.bnema.dev/docs) · [Keybindings](https://dumber.bnema.dev/docs/reference/keybindings)
12
13## Demo
14
15https://github.com/user-attachments/assets/232822af-08e4-4a74-9416-87f79c96b118
16
17The demo shows split panes, stacked panes, modal navigation, and workspace switching.
18
19## Overview
20
21Dumber uses three layout levels:
22
23- **Tabs** group separate browser contexts.
24- **Workspaces** hold a layout of panes.
25- **Panes** display web pages and can be split, stacked, moved, resized, or closed.
26
27Most browser-management actions are exposed through modal keybindings. Enter a mode, run one or more commands, then leave the mode. The default modes cover pane management, tabs, resizing, and session commands.
28
29The browser chrome stays out of the way by default. Open the omnibox when you want to navigate; otherwise the pane is just the page or web app you are using. This makes Dumber work well as a side pane next to an editor, terminal, or another desktop application.
30
31## Features
32
33### Content-first browsing
34
35- No permanent tab bar, bookmark bar, or toolbar around the page
36- Omnibox and browser commands appear through keyboard shortcuts
37- Web apps can feel closer to desktop applications because the browser frame is not always visible
38- Works well as a narrow side pane next to an editor, terminal, or other application
39
40### Pane-based browsing
41
42- Split panes horizontally or vertically
43- Stack panes in the same area
44- Move, resize, and close panes with modal keybindings
45- Keep related pages together in a workspace
46
47### Keyboard workflow
48
49- Pane, tab, resize, and session modes
50- Vim/Zellij-style navigation patterns
51- Search bangs such as `!g`, `!gi`, and `!ddg`
52- Launcher integration for `rofi`, `fuzzel`, and `dmenu`
53
54### Desktop integration
55
56- Wayland-native on Sway, Hyprland, River, Niri, and similar compositors
57- Floating pane with configurable profile shortcuts
58- Single `config.toml` file with hot reload
59
60### Browser features
61
62- Chromium Embedded Framework backend by default
63- WebKit backend available as a fallback
64- Built-in ad blocking based on uBlock filter lists
65- GPU-accelerated video through VA-API/VDPAU where supported
66- Snapshot-based restoration of tabs, workspaces, and pane layout
67
68## Installation
69
70### Install script
71
72```bash
73curl -fsSL https://dumber.bnema.dev/install | sh
74dumber browse
75```
76
77### Arch Linux
78
79```bash
80yay -S dumber-browser-bin   # Pre-built binary
81yay -S dumber-browser-git   # Build from source
82```
83
84### Flatpak
85
86```bash
87wget https://github.com/bnema/dumber/releases/latest/download/dumber.flatpak
88flatpak install --user dumber.flatpak
89flatpak run dev.bnema.Dumber browse
90```
91
92For dependencies, distribution notes, and troubleshooting, see the [installation documentation](https://dumber.bnema.dev/docs).
93
94## Keyboard modes
95
96Dumber uses modal keybindings for browser management.
97
98| Mode | Default key | Used for |
99|------|-------------|----------|
100| Pane | `Ctrl+P` | Split, stack, close, and move panes |
101| Tab | `Ctrl+T` | Create, close, switch, and rename tabs |
102| Resize | `Ctrl+N` | Resize panes with `hjkl` or arrow keys |
103| Session | `Ctrl+O` | Snapshot, restore, and browse sessions |
104
105## Floating pane
106
107The floating pane is a temporary browser pane that can be toggled without changing the main workspace layout.
108
109- `Alt+F` toggles the floating pane and preserves its state while hidden.
110- `Ctrl+W` closes the active pane; if the floating pane is active, it is fully released for a fresh next open.
111- Profile shortcuts such as `Alt+G` are optional and configured under `workspace.floating_pane.profiles`.
112- Some `Alt+<key>` bindings may conflict with browser-engine shortcuts or desktop-level handlers.
113
114See the [floating pane reference](https://dumber.bnema.dev/docs/reference/floating-pane) for setup and behavior details.
115
116## Configuration
117
118Dumber is configured with a single TOML file.
119
120```toml
121[engine]
122type = "cef"
123
124[workspace.floating_pane]
125enabled = true
126```
127
128The config reloads while Dumber is running. See the [configuration documentation](https://dumber.bnema.dev/docs) for all options.
129
130## Browser engine
131
132Dumber uses Chromium Embedded Framework by default. WebKitGTK is available as a fallback backend.
133
134On Arch Linux, install the CEF runtime with:
135
136```bash
137sudo pacman -S cef
138```
139
140For hardware video decoding, `cef-vaapi` is also available from the AUR as an optional CEF build.
141
142CEF runtime lookup order:
143
1441. `CEF_DIR`
1452. `engine.cef.cef_dir`
1463. `/usr/lib/cef`
1474. `~/.local/share/cef`
148
149Set `engine.cef.cef_dir` in config when `CEF_DIR` is unset:
150
151```toml
152[engine.cef]
153cef_dir = "/custom/path"
154```
155
156Or set the higher-precedence `CEF_DIR` environment variable:
157
158```bash
159CEF_DIR=/custom/path dumber browse
160```
161
162WebKit can be selected explicitly:
163
164```toml
165[engine]
166type = "webkit"
167```
168
169### Rendering notes
170
171CEF uses Dumber's GPU-first Wayland render stack by default: GDK DMABUF presentation with ANGLE/GSK Vulkan. For driver compatibility, switch to the EGL/OpenGL stack with `engine.cef.render_stack = "egl"`; the default is `"vulkan"`.
172
173CEF OSR frame rate adapts to the active Wayland monitor refresh rate when both `engine.cef.adaptive_windowless_frame_rate = true` and `engine.cef.windowless_frame_rate = 0` are set, which are the defaults. Adaptive mode is capped by `engine.cef.windowless_frame_rate_max = 240`. Setting `engine.cef.windowless_frame_rate` to a positive value forces a fixed rate instead. This adaptive polling path is Wayland-specific; other platforms fall back to the configured fixed/default CEF behavior.
174
175## Platform notes
176
177### Dependencies
178
179**Arch Linux:**
180
181```bash
182sudo pacman -S cef webkitgtk-6.0 gtk4 gst-plugins-base gst-plugins-good gst-plugins-bad gst-plugin-va
183```
184
185**Debian/Ubuntu:**
186
187```bash
188sudo apt install libwebkitgtk-6.0-4 libgtk-4-1 gstreamer1.0-plugins-base gstreamer1.0-plugins-good gstreamer1.0-plugins-bad
189```
190
191> Ubuntu 24.04 ships GLib 2.80, but Dumber requires GLib 2.84+. Use Arch, Fedora 41+, or the Flatpak.
192
193## Status
194
195Dumber is usable for regular web browsing on Wayland compositors, with the main focus on panes, keyboard control, floating workflows, and desktop integration.
196
197It is not a drop-in replacement for every mainstream browser workflow. Extension compatibility, engine behavior, and media support depend on the selected backend and system libraries.
198
199Bug reports and reproducible Wayland/backend issues are welcome.
200
201## Development
202
203Dumber uses pure-Go bindings. The GUI uses GTK4, runs on CEF by default, and can use WebKitGTK as a fallback backend.
204
205Set `ENV=dev` to use `.dev/dumber/` for config and data instead of XDG paths.
206
207### Build from source
208
209**Prerequisites:**
210
211- Go 1.26+
212- GTK4 development packages
213- CEF runtime (default backend)
214- WebKitGTK 6.0 development/runtime packages (fallback backend and runtime checks)
215- Brotli for compressed systemviews assets
216
217Systemviews assets are generated with `go tool templ` and Go's `js/wasm` toolchain; no root Node toolchain is required.
218
219```bash
220git clone https://github.com/bnema/dumber
221cd dumber
222make build
223./dist/dumber browse
224```
225
226### Make targets
227
228| Target | Description |
229|--------|-------------|
230| `make build` | Build systemviews assets and binary |
231| `make build-quick` | Build binary only, skipping systemviews assets |
232| `make check` | Run local all-clear checks for tools, build, generated assets, tests, and constraints |
233| `make dev` | Run with `go run` |
234| `make test` | Run tests |
235| `make lint` | Run the pinned golangci-lint version |
236| `make staticcheck` | Run Staticcheck with the pinned tool version |
237| `make verify-generated` | Verify generated systemviews artifacts are committed |
238| `make flatpak-build` | Build Flatpak bundle |
239
240Development tool versions are pinned in `Makefile` (`GOLANGCI_LINT_VERSION`, `STATICCHECK_VERSION`). Bump those values intentionally when refreshing lint/static analysis tooling.
241
242## Contributing
243
244Dumber is currently focused on stability, performance, browser-engine behavior, and core UI/UX polish.
245
246Bug fixes, documentation improvements, packaging fixes, and targeted UX improvements are welcome. Larger feature ideas should start as issues before PRs.
247
248See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
249
250## Community
251
252- [Report bugs](https://github.com/bnema/dumber/issues)
253- [Releases](https://github.com/bnema/dumber/releases)
254
255## License
256
257MIT - See `LICENSE` for details.