GitHub - tobagin/karere: Gtk4 Whatsapp client

7 min read Original article ↗

Multi-account & identity discovery. Each account runs in an isolated CEF RequestContext; accounts are listed most-recently-used (no manual ordering), and existing v3 accounts must be re-linked (no migration). Account name and avatar are discovered from WhatsApp Web's internal Store through a Webpack hook (the same technique as @wppconnect/wa-js).

Degraded-mode contract. If a future WhatsApp release restructures its Webpack bundle and the Store hook can't attach, the affected account falls back to scraping the DOM (#side header) for its name and avatar, and its switcher row shows a persistent yellow "degraded mode" badge. The badge does not clear when the DOM fallback succeeds — it is cleared only when a later page load lets the Store hook attach successfully again (typically after the hook is updated for the new WhatsApp release). The badge is intentional: it surfaces the fragile scrape path so it gets fixed rather than silently masking breakage.

A fast, native WhatsApp client for Linux that feels right at home on your desktop.

🎉 Version 4.1 — CEF/Chromium 149

Karere 4.0 is a ground-up rewrite that swaps the rendering backend from WebKitGTK to the Chromium Embedded Framework (CEF/Chromium 149) while keeping the same native GTK4/libadwaita shell. It is a hard fork of Karere v3: there is no automatic migration — existing accounts must be re-linked by scanning the QR code again on first launch.

Why CEF?

WebKitGTK could not play WhatsApp Web's video attachments (a platform-level limitation shared by all WebKitGTK browsers). Chromium handles them natively. The CEF build ships with proprietary codecs (H.264/AAC), so video attachments now play in-app.

🆕 What's New in 4.1.2

  • GNOME OS / Wayland black window fixed for real (#164): CEF was racing to the X11/Xwayland Ozone backend and failing to present onto the Wayland view (black even with the 4.1.1 GL-renderer change). Karere now forces CEF's Ozone backend to match the display server, removing the race.

Recent in the 4.1 line: mobile-layout keeps the message box focused on Enter on desktop, and the bundled browser engine moved to CEF/Chromium 149.

Migration from v3. None. v3 stored sessions under WebKit's data manager; v4 uses CEF RequestContext directories and a new account record format. On first v4 launch, re-scan the QR code for each account.

For the full release history, see CHANGELOG.md.

Features

Core Features

  • Native Experience: Designed to look and feel like a native application on your desktop.
  • System Integration: Notifications, themes, and shortcuts work exactly as you expect.
  • Privacy Focused: Sandboxed communication with comprehensive privacy controls.
  • Efficient: Optimized to be lightweight and fast.

User Experience

  • System Tray Icon: Dynamic icon showing unread status, with background run support
  • Notification Sounds: Plays WhatsApp Web's own notification sound for new messages, with an on/off toggle
  • Image & Text Paste: Seamless Ctrl+V support for both mixed content types
  • Download Manager: Custom directory selection (e.g., ~/Downloads) with toast notifications

Accessibility

  • Screen Reader Ready: Fully labeled interface for screen reader users.
  • Keyboard Navigation: Use the entire app without a mouse.
  • Visual Aids: High contrast support, zoom controls, and reduced motion.
  • Auto-Correct: Smart text correction with dictionary support

Spell Checking

  • Multi-Language Support: 80+ dictionaries from LibreOffice
  • Auto-Detection: Smart language detection based on system locale
  • Dictionary Management: Override auto-detect to select specific languages
  • Auto-Correct Toggle: Enable or disable automatic text replacement

Privacy & Customization

  • Granular Notification Controls: Master toggle, plus individual settings for sound on/off, previews, and downloads
  • Privacy Settings: Control message previews and system tray behavior
  • Theme Selection: Light, Dark, or System preference
  • Permission Management: Persistent controls for Microphone and Notifications
  • Startup Control: Toggle automatic launch on login

Building from Source

# Clone the repository
git clone https://github.com/tobagin/karere.git
cd karere

# Build and install development version
./build.sh --dev

Build dependency: the UI is authored in Blueprint (data/ui/*.blp, including preferences.blp and keyboard-shortcuts.blp) and compiled to .ui at build time. blueprint-compiler must be on PATH for a local cargo build; the Flatpak SDK (org.gnome.Sdk//50) already ships it, so the Flatpak build needs no manifest change.

Note: After installation, you'll need to scan the QR code with your mobile WhatsApp to connect.

Usage

Basic Usage

Launch Karere from your applications menu or run:

flatpak run io.github.tobagin.karere

The application will load WhatsApp Web and provide native desktop integration.

Preferences

Access preferences through the application menu or keyboard shortcut (Ctrl+,) to configure:

  • General: Theme selection, developer tools
  • Accessibility: Keyboard shortcuts, focus indicators, high contrast, reduced motion, zoom settings, screen reader optimization
  • Notifications: Native notification preferences, preview settings, background notifications
  • Spell Checking: Multi-language spell checking with auto-detect

Keyboard Shortcuts

Standard

  • Ctrl+N - New Chat
  • Ctrl+, - Open Preferences
  • Ctrl+Q - Quit Application
  • F1 - Show Keyboard Shortcuts Help

Zoom

  • Ctrl++ - Zoom In
  • Ctrl+- - Zoom Out
  • Ctrl+0 - Reset Zoom

Developer (when enabled)

  • Ctrl+Shift+D - Open Developer Tools
  • Ctrl+R - Reload Page

WhatsApp Web

  • Ctrl+F - Find in Chat
  • Ctrl+Shift+F - Search Chats

Accessibility Features

Karere includes comprehensive accessibility support:

  • Screen Reader Support: Full ARIA labels and semantic HTML
  • Keyboard Navigation: Complete keyboard-only navigation with visible focus indicators
  • High Contrast Mode: Automatic detection and adaptation
  • Reduced Motion: Respects system reduce-motion preferences
  • Configurable Shortcuts: All keyboard shortcuts can be enabled/disabled
  • Focus Management: 82 focusable elements in a logical focus chain

Architecture

Karere is built using modern GNOME technologies:

  • Rust: Primary programming language for memory safety and performance
  • GTK4: Modern toolkit with excellent Wayland support
  • LibAdwaita: Native GNOME design language and components
  • CEF / Chromium 149: Chromium Embedded Framework renders WhatsApp Web (off-screen, composited into a GTK GLArea)
  • Blueprint: Declarative UI definition language
  • Flatpak: Secure application distribution

Privacy & Security

Karere is designed with privacy in mind:

  • Sandboxed: Runs in a Flatpak sandbox with minimal permissions
  • Opt-in Telemetry: All logging and crash reporting is disabled by default
  • Local Storage: Uses standard user data directories, no external services
  • Transparent: Open source code available for audit

Known Limitations

Video Attachments

Video attachments now play in-app. The v4 CEF/Chromium 149 backend ships with proprietary codecs (H.264/AAC), removing the WebKitGTK platform limitation that blocked video playback in v3 and earlier.

Voice & Video Calls

Calling requires WhatsApp Web's beta program. Voice and video calls are still a beta feature on WhatsApp Web itself — the call buttons only appear once your account is enrolled in the WhatsApp Web beta. Karere provides the codecs and permissions plumbing (microphone/camera prompts, H.264/AAC), but it cannot surface call controls that WhatsApp Web does not expose. To enable them, join the beta from the official WhatsApp client (Settings on your phone, or the WhatsApp Web beta opt-in); calls then work in Karere like any other WhatsApp Web feature.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines on:

  • Setting up your development environment
  • Code style and conventions
  • Testing and building
  • Submitting pull requests
  • Reporting bugs and feature requests

For questions or discussions, please use GitHub Discussions.

License

Karere is licensed under the GNU General Public License v3.0 or later. See LICENSE for the full license text.

Support

Acknowledgments

  • GNOME Project: For the excellent GTK4 and LibAdwaita frameworks
  • Chromium / CEF Project: For the Chromium Embedded Framework rendering engine
  • Rust Community: For the amazing language and tools
  • WhatsApp Inc.: For WhatsApp Web

Screenshots

Main Window About Dialog
Main Window About
Preferences Shortcuts
Preferences Shortcuts

Karere - Native WhatsApp Web client for Linux desktop environments.