Skip to content
AndiveliPublic

About

Keyboard-driven WhatsApp client for the terminal (Rust/Ratatui + Go/whatsmeow)

Topics

Resources

Contributing

Stars

203 stars

Watchers

0 watching

Forks

Repository files navigation

wptui

A keyboard-driven WhatsApp client for the terminal.

wptui pairs a Rust Ratatui interface with the Go whatsmeow library, giving you a fast, Vim-flavored chat experience without leaving your terminal.

Demo

demo.mp4

Warning

This project is under active development. Features and behavior may change between versions.

Features

  • Link a WhatsApp account with a QR code or a phone pairing code
  • Browse and search chats from the terminal
  • Send, reply to, edit, delete, copy, and react to messages
  • Inspect reactions and quoted messages
  • See who is typing in the open conversation, including multiple people in a group
  • Paste text, images, and files from the clipboard
  • Send attachments with captions
  • Download and preview media, or open it in an external player
  • Play animated WebP stickers while visible in terminals with image support (up to four animations at a time, prioritizing visible stickers as you scroll); long animations are sampled to preserve motion and their normalized frame timing within bounded memory, while excess simultaneous or unsupported stickers retain a still preview
  • Display contact avatars and desktop notifications
  • Contextual, Vim-inspired keybindings
  • Andiveli welcome mark in the chat panel before any conversation is opened

The Chats list has All, Unread, Groups, and Archived views. Search in All also finds saved contacts without chat history. To start a chat with an unsaved number, type / in the Chats list, enter + followed by 7–15 digits (country code included), and press Enter. The app checks whether the number is registered on WhatsApp before opening an empty conversation; it never sends a message automatically. All, Unread, and Groups exclude archived chats; Archived shows only archived chats. Filter badges count unread chats (each chat once), including manually marked chats, not individual messages. All, Unread, and Groups count unarchived chats; Archived counts archived chats. Zero counts are hidden. Archive status comes from the linked device's WhatsApp settings. Search narrows the selected view. Switching views does not change messages or read status; a community row contains only groups in that view. Archive changes received from WhatsApp refresh the current view without switching filters. A yellow @ and yellow Archived label signal an unread mention or reply to your message in an archived group; ordinary archived chats and other group messages do not trigger it. Reading that group clears the alert.

Message formatting

Messages and attachment captions render WhatsApp formatting locally: *bold*, _italic_, ~strikethrough~, inline backticks, triple-backtick code, quotes, and lists. wptui also recognizes **bold**, __bold__, ~~strikethrough~~, # headings, and [label](https://example.com) links. Headings and quotes also recognize markers after up to three leading ASCII spaces, preserving indentation in the display projection and original source. Labeled links show only an underlined label; clicking it opens the original URL. The active composer fragment reveals the link source for editing. Formatting never fetches content or opens a link automatically.

Incoming and outgoing chat text display bare HTTP(S) URLs as the complete host (including subdomains and any port) plus the final nonempty path segment: for example, https://github.com/Andiveli/wptui becomes github.com · wptui, while https://example.com/ becomes example.com. Query strings and fragments are omitted from the label, not the click destination; path segments are not decoded. Ambiguous or unsupported authorities remain raw. This helps you inspect the host, but is not phishing detection or a safety guarantee. No site or title is fetched. Explicit Markdown links retain the author's chosen label rather than a URL label. The composer, statuses, captions, reply summaries, system text, code, and literal image syntax keep their existing display.

When WhatsApp supplies native preview metadata for an eligible incoming or outgoing chat link, bare or explicit Markdown, a compact preview below the body shows its title and description literally (not as Markdown). Only an embedded JPEG can supply the thumbnail; no website, external image URL, or thumbnail direct path is fetched. The host/path or chosen Markdown label and exact click destination remain unchanged. The card binds to the original source occurrence: a protected code/image occurrence cannot borrow eligibility from a later matching URL. Missing or invalid metadata keeps the normal link presentation. Optimistic desktop sends may lack metadata; synced phone-sent messages can carry it. wptui does not generate preview metadata. Thumbnail work is automatic only while its entire reserved image area is visible and not covered by a popup; selection and keyboard focus do not trigger loading. Loading or unusable images keep the same reserved geometry and leave the text and original link usable. The preview adds no clickable card action.

Formatting changes only the local display. Sending, editing, copying, and searching still use the original text; other WhatsApp clients display the syntax they support. The composer previews the same formatting while you type. Markers reappear in the fragment containing the cursor, so you can edit them directly; outside that fragment they do not occupy columns. Drawing, wrapping, and arrow-key navigation share the source-to-display mapping, including Unicode and right-to-left text.

Incomplete markers and unsupported Markdown remain literal. Code is displayed without interpreting formatting inside it. Terminal font support determines whether italic and strikethrough styles are visible.

Data

Your WhatsApp data — database, media, and session — lives in ~/.local/share/wptui/ on your machine. It is not uploaded anywhere; the client only exchanges data with the WhatsApp servers when it links or syncs, like any official client.

Startup reads chats, contacts, messages, reactions, and native link-preview metadata as one SQLite snapshot before applying that history to the app. If hydration fails (for example, an exhausted SQLite lock wait), wp-tui prints wp-tui: could not hydrate persisted chat history: <error> and exits with status 1 without connecting to WhatsApp or opening the terminal UI. It does not treat a failed read as empty or partially loaded history, retry it, or extend the existing SQLite busy timeout. This error alone does not identify which connection holds a lock.

Incoming and outgoing chat text can retain WhatsApp-supplied link-preview metadata in a separate local database table; old messages without metadata load normally. Native metadata is optional and is displayed only for eligible plain or explicit Markdown chat links in either direction: no website, external image URL, or thumbnail direct path is fetched. Titles are limited to 2,048 UTF-8 bytes, descriptions to 8,192 bytes, and embedded thumbnails to 256 KiB; an oversized image is omitted without discarding valid text metadata. Unsafe or mismatched text metadata is ignored without changing the message or its click destination. Editing or deleting a message clears its preview metadata. Receive adjuncts and app-owned preview state are bounded (64 and 256 entries, respectively); valid persisted metadata remains associated with its message.

Preferences live in your OS configuration directory (~/.config/wptui/settings.conf on Linux). An existing settings.conf in the data directory is copied there on first use if no config file exists; the legacy file is left untouched. Set composer_direction=rtl or composer_direction=auto to choose the composer direction.

Built-in dark themes

Press Space → a → t (Actions → Themes) to choose Default, Kanagawa, One Dark, Catppuccin, Tokyo Night, Gruvbox, or Custom. The current selection is highlighted. Move with Up/Down or j/k; Enter saves and applies immediately without restarting, and Esc cancels without changing settings or colors. A save failure is displayed and leaves the current colors unchanged. Selecting Default clears all earlier theme selections; other settings are preserved.

Alternatively, add one line to ~/.config/wptui/settings.conf on Linux (or your OS configuration directory) and restart:

theme=kanagawa
Setting value Variant
kanagawa Kanagawa Wave
one-dark One Dark Pro
catppuccin Catppuccin Mocha
tokyo-night Tokyo Night
gruvbox Gruvbox Dark Medium

Names are case-sensitive; surrounding whitespace is ignored. Omit theme, leave it empty, or use an unknown name to retain the existing default appearance. If repeated, the first recognized theme wins, as with other parsed preferences. Theme loading does not rewrite your settings or change mouse, composer, notification, or custom preferences.

Named themes paint an explicit dark canvas and selection fill, so contact names, previews, timestamps, unread indicators and attention markers do not depend on your terminal's background or ANSI palette. The same text, secondary, accent, selection, unread, attention and border roles are used across navigation, contacts, communities, Status, News and the conversation/composer chrome. Existing message formatting and media colors are not remapped. Custom palettes are supported through the JSON file below; there is no transparency toggle.

Secondary text and borders use brighter base-palette roles rather than low-contrast editor comments or separators: Kanagawa's status foreground, One Dark's status foreground, Catppuccin's ANSI white, Tokyo Night's bright white, and Gruvbox's ANSI white. Selection uses each variant's opaque list surface (Gruvbox's focus surface) with light text. Unread/attention use the palette's bright green/yellow roles (Catppuccin uses its regular pastel green/yellow). These adaptations keep small terminal text readable; rendered contact regression tests require at least 4.5:1 contrast on the explicit surfaces. Palette provenance is recorded in Third-Party Notices.

Custom themes

To use your own colors:

  1. Create theme.json beside your active settings.conf (~/.config/wptui/theme.json on Linux).
  2. Choose Custom using Space → a → t, then Enter to save and apply. Selecting Custom again reads the current JSON file without restarting.

You can also set theme=custom in settings.conf, replacing earlier recognized theme entries, and restart. Manual settings-file edits require a restart; JSON edits require a restart or selecting Custom again. There is no file watcher or in-TUI color editor, and the selector never rewrites theme.json.

For example:

{
  "base": "kanagawa",
  "colors": {
    "text": "#DCD7BA",
    "accent": "#aB12Ef",
    "surface": "#1F1F28"
  }
}

The schema is a JSON object with only these optional fields:

Field Accepted value When omitted
base One of kanagawa, one-dark, catppuccin, tokyo-night, gruvbox (case-sensitive) kanagawa
colors An object mapping the roles below to color strings; {} is allowed No overrides

The ten allowed color roles are text, muted, accent, selection, selected_text, unread, attention, border, surface, and error. selection is the selected-row fill; selected_text is its foreground; surface is the opaque canvas. Unspecified roles inherit the base palette, so {} is a complete valid theme using Kanagawa unchanged.

Every color must be exactly #RRGGBB, with six hexadecimal digits; upper, lower, and mixed case are accepted. Short hex, alpha channels, color names, transparency, and surrounding whitespace inside the string are not accepted. Contrast is your choice: custom colors are not automatically adjusted or rejected for low contrast. Custom themes keep the same explicit opaque canvas as named ones, using the resolved surface color.

Malformed JSON, unknown fields or roles, an invalid base, wrong value types (including null), or any invalid color reject the whole file. Missing or unreadable files likewise use the legacy default appearance, not the base palette; no partial overrides are applied. The first recognized theme setting still wins: theme=custom remains selected even when its file falls back, rather than trying later duplicate settings.

The file is read only when custom is selected. Lookup follows the resolved settings.conf location: after legacy settings migration, the active configuration directory wins, and a theme.json left in the data directory is not migrated or used. Startup theme loading only reads files: it does not create, rewrite, or repair either file or alter other preferences. Applying a selection in the TUI updates only theme entries in settings.conf, removing duplicates. Paths, includes, plugins, and executable code are not supported in the schema.

Desktop notifications

Press Space, then a, then n to toggle all WPTUI desktop notifications and their audio. The contextual menu shows the current Notifications: On / Notifications: Off state; changes apply immediately and are saved to the same settings file. No chat selection is needed. If saving fails, an error is shown and the current state is kept.

Alternatively, to disable them manually, add this to settings.conf:

notifications=disable

Use notifications=enable to enable them explicitly. Notifications are enabled by default when the setting is missing, invalid, or unreadable. Manual file edits are loaded at startup; restart WPTUI after editing the file (the menu toggle needs no restart). Disabling notifications does not change message reception, persistence, synchronization, or unread counts. The existing notification_sound option selects the sound only when notifications are enabled.

Notification sounds

Eligible desktop notifications play the bundled assets/sounds/attention.wav by default, even when the notification server does not support sound hints. To use your OS/theme sound instead, set notification_sound=system in settings.conf (this requests a system sound hint; it depends on your notification server). To play your own sound directly, set notification_sound=/absolute/path/to/alert.ogg (WAV, MP3 and OGG/Vorbis are supported). Absent or invalid settings use the bundled sound. Direct playback does not request a second system sound; an unreadable file or missing audio device is logged without suppressing the desktop notification. Messages timestamped before this app session started still show desktop notices, but request neither bundled/custom audio nor a system sound hint. Messages from the startup second onward remain audible, even while synchronization progress is visible. If the startup clock is unavailable, audio remains enabled for eligible notices. Muted chats, open chats and explicit sync traffic remain silent.

Mouse capture

Mouse capture is enabled by default during the pointer-support preview. Add mouse=disable to that config file and restart to restore terminal-native selection, or use mouse=enable to explicitly enable terminal-wide capture. When capture is on, Shift+drag may allow native text selection depending on your terminal; it cannot be enabled for individual panes. In this preview, the wheel scrolls painted lists. Clicking a section enters its list, clicking a contact opens it, and clicking an ordinary text message selects it and opens its Enter actions. Clicking a painted URL opens that link, while clicking a file's painted media/path opens the image/video viewer or uses the existing downloaded document/audio action. Empty file-row space only selects. Mouse behavior still needs a fresh live-terminal check.

Requirements

Runtime dependencies

The prebuilt binary links against a few system libraries. On a desktop installation most of them are already present; the one you usually need to install explicitly is libchafa, which is used to render images in the terminal.

  • Debian / Ubuntu
    sudo apt install libchafa0t64 libglib2.0-0 libwayland-client0 libasound2
    
  • Fedora
    sudo dnf install chafa glib2 wayland alsa-lib
    
  • Arch Linux
    sudo pacman -S chafa glib2 wayland alsa-lib
    
  • macOS
    brew install chafa
    
    macOS uses the native file dialogs, so no Wayland libraries are needed.

Build requirements

  • Linux or macOS
  • A recent stable Rust toolchain with Cargo (the repository pins Rust 1.96.1 via rust-toolchain.toml)
  • Go with CGO enabled
  • A C compiler supported by CGO
  • On Linux, the development packages libwayland-dev, libchafa-dev and libglib2.0-dev, libasound2-dev; on macOS, chafa from Homebrew
  • Optional: mpv for opening media externally

Media previews and external opening require a kernel-confined file open (Linux openat2 or macOS O_RESOLVE_BENEATH). On older systems without that support, these operations fail closed; downloads and chat still work. Symlinks whose resolved targets remain inside the media directory, including absolute links, remain usable on supported systems. Video thumbnails are generated from confined input handles into bounded memory: generated frames are not saved as sidecars and may be regenerated after a restart or cache eviction. FFmpeg must support seekable fd: input; otherwise an existing contained sidecar remains the fallback. Audio duration probes also read already-confined file handles, not media pathnames.

Installation

Prebuilt binary

Prebuilt binaries for Linux (x86_64) and macOS (Apple Silicon) are attached to each GitHub release. Install the one for your system with:

curl -sSL https://raw.githubusercontent.com/Andiveli/wptui/main/install.sh | bash

The script downloads the matching binary from the latest release into ~/.local/bin (override with PREFIX, e.g. PREFIX=/opt/wptui ./install.sh). New release archives include the bundled tone's MIT notice; the installer keeps it next to the binary as wp-tui-THIRD_PARTY_NOTICES.md. Make sure the runtime libraries listed in Requirements are present first.

Nix (Linux)

The flake declares wp-tui for x86_64-linux and aarch64-linux; CI builds only the x86_64 Linux package. From a checkout, build the package or run it from the development shell:

nix build .#default
./result/bin/wp-tui --version
nix develop --command wp-tui --version

Run nix develop without --command to enter a shell with wp-tui on PATH. When using the repository as a NixOS flake input, select inputs.wptui.packages.x86_64-linux.default on x86_64 Linux (or inputs.wptui.packages.aarch64-linux.default on ARM Linux).

Build from source

git clone https://github.com/Andiveli/wptui.git
cd wptui
cargo install --path .

The Rust build automatically compiles the bundled Go bridge. See Requirements for the build-time libraries.

Usage

Start the client and scan the QR code displayed in the terminal:

wp-tui

Or request a pairing code using an international-format phone number:

wp-tui --phone +1234567890

Check for and install the latest stable release when using a standalone binary:

wp-tui update

The updater accepts older binary-only archives and newer archives containing the bundled tone's MIT notices. It keeps wp-tui-THIRD_PARTY_NOTICES.md beside the updated executable.

News wptui

The muted blue-gray News wptui section (or News on a narrow rail) bundles notes for the installed version and reads GitHub's published stable releases, newest first, including intermediate newer versions. It does not show main, drafts, or prereleases. The v0.3.0 release has no supplied notes; the bundled text says so rather than inventing highlights. Maintainers should update assets/release-notes.md with the installed release's notes before building and use the same text in the GitHub release description; follow the release checklist.

History is limited to eight pages of 100 entries, 1 MiB per page and a three-second request timeout. Reaching the page cap explicitly marks history incomplete. A failed request returns cached newer-version notes marked stale with an error; missing or corrupt cache never implies the installation is up to date. Cache replacement is atomic, and cached content is untrusted display data, not authority to install a binary. Terminal control sequences are stripped before display.

History loads asynchronously at startup and r refreshes it (one request at a time). The dedicated news-history.json file lives in the OS cache directory. Installed notes remain available offline. Loading, offline/cached, error and incomplete history are labeled explicitly; a failed fetch never means “up to date”. Select installed or intermediate release notes with j/k or arrows; use Ctrl+U/Ctrl+D to scroll long notes. h/l or left/right arrows move pane focus; Tab advances focus inside News. The mouse wheel selects releases over the list and scrolls notes over the body.

News also offers an optional highlighted Star Andiveli/wptui invitation when GitHub CLI (gh) confirms the repository is not starred. Status is checked once per session on entering News, in the background with an eight-second timeout. Already-starred, checking, unavailable, unauthenticated and unknown states hide the invitation; gh is optional and release notes work without it. Only pressing s in News or clicking Star sends the explicit GitHub star request. While it is pending, both actions are disabled; success shows inline thanks, and failure quietly hides the invitation. Press d in News or click Hide to permanently dismiss it (stored separately in the app data directory, not configuration). Unreadable or unwritable invitation state suppresses it. These keys do not change Messages Share/Delete or Status Delete. No browser or notification is opened.

Press u to install the exact displayed newer stable release, including an intermediate version. The confirmation names that version; Cancel is selected by default. Use Up/Down to choose, Enter to confirm, or Esc to cancel. Installed-version notes cannot be installed. The updater re-fetches the exact tag from the trusted GitHub API; cached notes never authorize installation. Package-manager, platform, ownership, checksum and archive protections remain enforced. A working status covers checking/downloading/installing; errors remain visible and requests are single-flight.

After success, choose Restart now / Later (Later is the safe default). Later keeps the current version and session running; R opens the restart choice again. Restart is deferred while drafts, attachments, status composition or pending sends exist: finish or discard them and press R again. Nothing logs you out. Explicit restart shuts down normally, joins update/history work, restores the terminal and executes the newly installed binary with the same arguments and environment. If relaunch fails, the restored terminal shows an error and exits nonzero; session data is untouched. Ordinary quit also waits for an installation to finish. wp-tui update retains its existing latest-stable behavior and safety checks.

When running through Cargo, separate application arguments with --:

cargo run -- --phone +1234567890

Number lookup notices

When a number check finishes unsuccessfully, it leaves the search open without opening a conversation or sending a message. Its result notice appears as plain text; local input validation and unrelated notices retain their existing formatting:

Notice Meaning / next step
Number is not on WhatsApp WhatsApp reported that the requested number is not registered.
Number check timed out The check exceeded its deadline; retry the search.
WhatsApp returned no number result No result was returned; retry the search.
WhatsApp returned a mismatched number result A registered reply matched the query but had empty or unexpected identities that did not confirm the requested number; no recipient is opened. Retry the search.
WhatsApp returned only a LID without a phone number A registered reply matched the query with a LID and no associated phone number, without confirming the requested number; no recipient is opened.
WhatsApp returned a different phone number A registered reply matched the query and contained a phone-number identity, but neither identity confirmed the requested number exactly or through the narrow Mexico/Argentina equivalences below; no recipient is opened.
WhatsApp returned a mismatched query result Nonempty replies contained no matching query; no recipient is opened. Retry the search.
Could not check number The request failed; retry the search.
Could not verify number The result could not be safely verified; no recipient is opened.
WhatsApp is not connected Reconnect WhatsApp, then retry the search.
Use + followed by 7-15 digits Correct the international number format, then retry.

A failed, timed-out, empty, or mismatched check does not mean the number is unregistered. These notices use fixed categories, without including the entered number, recipient identity, or raw error details; number lookup adds no diagnostic logging. The LID-only and different-phone-number categories describe response shape only: they do not prove legitimate number normalization or permit opening another recipient. Opening a conversation requires a registered response whose query matches the entered number (with or without its leading +) and whose phone-number identity confirms it. Exact matches take precedence across both returned identity fields. Otherwise, only these two country-number equivalences are accepted, in either direction:

  • Mexico: 52 + exactly 10 digits ↔ 521 + the same 10 digits.
  • Argentina: 54 + exactly 10 digits ↔ 549 + the same 10 digits.

All other digit differences remain rejected, including different national suffixes, wrong lengths, and unsupported countries. This is not domestic-number parsing: it does not strip Argentina's domestic 15 or leading zero, or guess area codes. For both exact and equivalent matches, only s.whatsapp.net and WhatsApp's legacy c.us user namespace are allowed, with the same integrator after device metadata is removed. An accepted equivalent lookup opens the server-confirmed spelling, not the originally entered spelling, as a non-device s.whatsapp.net PN identity. A LID alone never authorizes opening a conversation. No extra lookup is made and no message is sent automatically.

Temporary local number-response inspection

For the matched, registered response that failed the phone-identity comparison, this preview opens a local-only, read-only window. It shows the requested number, response Query and IsIn, and the PhoneNumber and JID fields. Each identity has a quoted string representation plus labeled User, Server, RawAgent, Device and Integrator components, so formatting and field order can be inspected without guessing.

Use j/k or up/down arrows to scroll vertically, h/l or left/right arrows to scroll horizontally, Home to reset the view, and Esc to close and release its in-memory observation. Other input is captured by the window: Enter does not open a conversation or send a message. Values are length-bounded and controls are escaped as visible ASCII rather than interpreted by the terminal.

Actual values are retained only in volatile memory for this display, with redacted Debug output. They are not added to notices, logs, files, the chat store, or the clipboard. No additional lookup is made; inspection never relaxes the recipient confirmation rules above. Do not share the displayed numbers, JIDs, screenshots, or full response text. Report only whether you see a formatting difference or different digits.

If the local snapshot is unavailable or exceeds its limits, the existing six-boolean comparison remains as a fallback, for example:

Lookup comparison PN(d/n/i)=0/1/1 JID(d/n/i)=0/0/1

PN compares the response's associated phone-number field; JID compares its other identity field. Each triple contains independent booleans (1 yes, 0 no):

  • d: the field's user digits exactly equal the entered phone-number digits.
  • n: its domain is an allowed phone-number domain (s.whatsapp.net or c.us).
  • i: its Integrator equals the requested identity's integrator (zero).

These are comparisons, not field values or proof of a valid recipient. An absent field can still have i=1 because its default integrator is zero. No number, JID, raw response, or diagnostic log is emitted or persisted by the boolean fallback. Only the existing lookup action makes a request; the preview adds no background queries, sends no message, and does not relax the recipient confirmation rules above. The comparison remains a rejected lookup and cannot open a conversation. Share only the comparison line, not the number, screenshot, or recipient identifiers. This temporary observation is not a fix for the reported new-number failure.

Diagnostics

To trace edited/deleted message processing, run with:

WPTUI_MESSAGE_ACTION_DEBUG=1 cargo run

After quitting, a bounded, redacted trace is printed in the normal terminal.

Read/unread synchronization preview

To diagnose a read/unread mismatch, use a diagnostic-enabled preview, without resetting your account or repairing local state. From the main checkout root:

The parent will provide the diagnostic-enabled binary's source-stamped filename. Replace SOURCE_STAMP below with that supplied stamp, keeping the old binary. The target directory must already exist. Each run creates a unique report directory:

trace_dir=$(mktemp -d "$PWD/.worktrees/chat-read-unread/target/read-sync-trace.XXXXXX") &&
  printf 'Read-sync report: %s/trace.txt\n' "$trace_dir" &&
  WPTUI_READ_SYNC_TRACE="$trace_dir/trace.txt" \
    .worktrees/chat-read-unread/target/release/wp-tui-SOURCE_STAMP

The report path is printed before the TUI starts. Preserve existing reports, archives and binaries; do not delete or overwrite them.

  1. Select the affected chat without opening it, then use Space, a, m.
  2. Reopen Space, a on that same chat and note the label and WhatsApp's state.
  3. Close the TUI normally with Ctrl+Q before inspecting the selected report.

The opt-in report is fresh-file-only: if the selected file already exists, capture is silently disabled and its bytes remain unchanged. A new report stops after 100 records across the app and bridge callbacks. It contains only stage enums, booleans, counters, bridge status and a safe error category—no message content, identifiers (even hashed), absolute message timestamps, keys, credentials, raw errors or server payloads. Without WPTUI_READ_SYNC_TRACE, this trace emits no output. Report I/O failure is nonfatal and can leave a missing or incomplete report; tracing adds no sends or retries.

Each completed bridge operation adds stage=initial_send, stage=recovery_fetch or stage=resend, followed by status=<code> category=<safe-category> using the existing closed outcomes. Omitted operations produce no stage record. The final stage=bridge status=<code> category=<safe-category> record is retained, so an initial rejection remains visible even if recovery succeeds or fails differently. These records are opt-in diagnostic evidence, not a synchronization fix or proof that WhatsApp applied the change.

Queue acceptance is not delivery confirmation. A bridge status of 0 only means the existing call returned successfully; resync_after_send means its follow-up fetch failed and the update may already have applied. missing_key, key_lookup, cancelled, timeout, unavailable and other do not establish server acceptance or a root cause. Exported typed errors use closed app-state, IQ, missing-element and connection/session categories, never raw error text or IQ codes; unknown IQ codes remain iq_other, and unrecognized errors remain other. appstate_with_cause only identifies an app-state error with a structurally wrapped secondary cause; it does not establish a server code, conflict, or specific cause. Known secondary sentinels use appstate_cause_key_missing, appstate_cause_content_mac, appstate_cause_index_mac, appstate_cause_lt_hash, appstate_cause_patch_mac, or appstate_cause_previous_set_missing. These identify error classes, not key/MAC values or a confirmed fix. Unknown secondary errors remain appstate_with_cause. Concurrent bridge results may appear between UI snapshots; there are deliberately no identifying correlation fields. Tracing alone does not repair synchronization.

Bounded read-state cache recovery

For the pinned client's compound app-state rejection with a secondary LTHash mismatch, the read/unread bridge attempts one official full sync of the affected collection, then calls SendAppState once more with the unchanged patch. This rebuilds that collection's version/hash/MAC cache, not messages, read cursors, receipts or the session; synchronized chat settings can refresh. Integrity checks remain enabled. Failed repair/resend does not loop or replenish the per-client, per-collection attempt budget. Publishing a different client starts a fresh budget. A post-accepted-send fetch error never triggers this recovery.

Recovery is disabled when full-sync action-event emission is enabled. Lifecycle transitions cancel active repairs without waiting for them or changing disconnect ordering; a canceled fetch must not be followed by a resend. The existing request deadline is inherited, not restarted per step. It is not a wall-clock guarantee while waiting on whatsmeow's non-context-cancellable app-state mutex. A successful bridge result still needs real WhatsApp validation; tests do not prove service sync.

Keybindings

Keybindings are contextual. Press Esc to close the active menu, picker, search, viewer, reply, or editor state.

The contact information pane keeps the conversation visible and shows a large profile photo, phone number (when known), and shared groups from the local known-group catalog. Membership is queried in the background; loading, unavailable, and empty results are shown separately. If some group queries fail, available matches remain visible with “Some groups unavailable”, including when no matches are found in the successful queries. An incomplete scan is never shown as “No known shared groups”; if every query fails, the pane shows “Shared groups unavailable”. This is not an account-wide group census. Unknown LID identities are never treated as phone numbers. Contacts without a profile photo use the illustrated default portrait; real photos still take precedence. Group and community artwork is unchanged.

At 180 columns the contact pane occupies 46 columns. Narrow terminals temporarily hide the section rail and chat list before reducing conversation space; very small terminals show contact details alone. Esc restores the normal layout without changing the draft. Composer and picker input retain priority; i returns to composing, and Space a i focuses details again.

Global and navigation

Action Key
Quit Ctrl+Q
Toggle section rail Space, then 1
Toggle chat list Space, then 2
Toggle notifications and audio (saved immediately) Space, then a, then n
Contact information (selected contact or open direct conversation) Space, then a, then i
Scroll contact details / close contact pane j / k, then Esc to close
Focus previous / next pane h / l or ← / →
Select previous / next item k / j or ↑ / ↓
Jump to first / last item g g / G
Move half a page Ctrl+U / Ctrl+D
Search chats or start a conversation / in the Chats list (All filter); type a name or + followed by 7–15 digits, then press Enter
Cycle chat filters (All, Unread, Groups, Archived) Tab in the Chats list
Selected chat: mark read / unread Space, then a, then m in the contact list

In the contact list, press Space, then a, then m to mark the selected visible chat as read or unread. The menu shows the next action and disables it when no chat is selected; this toggle is not available in Status. It queues WhatsApp chat app-state, not new message read receipts. Empty chats are supported. Marking unread adds an indicator and includes the chat in the Unread view without rewinding its read cursor or inventing a new-message count or mention alert. Opening the chat clears that manual indicator without moving the existing cursor anchor or clearing real unread messages. The manual flag is session-only locally: it is not restored from the local database after restart, though a subsequent WhatsApp app-state update can set it again. A queue rejection shows an error and leaves the manual action unapplied; queue acceptance is not server confirmation.

Known limitation: the contact-menu read/unread action has only been verified to update local TUI state. Remote WhatsApp app-state sends are still attempted, but current manual validation shows no synchronization with the phone. Do not rely on WhatsApp's read/unread state reflecting this action; synchronization remains unresolved. The diagnostics and bounded recovery described above do not establish a service-level fix.

Messages

Action Key
Start composing i
Search messages in the open chat history / with the conversation focused; Enter accepts, Esc cancels
Next / previous matching message (wraps) n / N after a chat search; j / k still navigate every message
Start optional Vim composer (Chats/Communities conversation only) Space, then v
Copy selected text y
React r
Share s
Reply R
Edit your text message e
Delete your text message d
Delete one selected, published own status (text, image, or video) d in Status navigation
Open downloaded media x
View selected image or video v
Open message actions Enter

With the message history focused, / searches the open chat's locally loaded text messages using a literal, case-sensitive substring. Type a query and press Enter to jump to its newest match, even if it is outside the viewport. The search line shows the match count and current position, or Sin coincidencias when nothing matches. Use n for older matches or N for newer matches (both wrap); j/k still visit every message. Esc clears the search. In the Contacts list, / still searches contacts, and / in the composer remains ordinary text. This does not search other chats, remote history, file captions, or media.

Consecutive photos and videos from the same sender share a main preview and count in chat history, for both received and sent messages. Up to three narrow slices of neighboring previews peek out to its right when space permits; the main preview stays anchored rather than right-aligning the whole panel. Text, other senders, date changes, deleted messages, and unread boundaries split piles. The newest message is shown by default. j/k still visit each original message; selecting a member brings its own preview, caption, quote, and actions to the front. The ordered neighbor window shifts horizontally with that selection, and reversing navigation restores its previous order; there is no timed animation. Preview slices load through the normal media worker and do not mark their hidden messages read. Only the front member counts as visible for read receipts. v starts on that member and still browses all photos/videos in the chat, not just its pile. Status updates retain their separate cards.

Use j/k or the arrow keys inside menus, then press Enter to confirm. Available actions depend on the selected message. In Status, press Enter on your own contact to open the Create status pane in navigation. Select one published update with j/k or ↓/↑, then press d to revoke it; i starts writing and Esc returns to the contact list. Space, a, c still opens Create status directly in authoring mode; Esc there enters navigation. Pending drafts and other contacts' statuses cannot be deleted this way. A failed revoke leaves the item visible; a successful send removes the local row, but does not itself prove removal from every recipient's device.

Composer and media

Context Action Key
Composer Send Enter
Composer Paste text, files, or an image Ctrl+V
Vim composer Normal Move cursor h/j/k/l
Vim composer Normal Next / previous word start w / b
Vim composer Normal Next / previous word end e / ge
Vim composer Normal Next / previous WORD start W / B
Vim composer Normal Next / previous WORD end E / gE
Vim composer Normal Yank to system clipboard (word/WORD motion) yw/yb/ye/yge/yW/yB/yE/ygE
Vim composer Normal Yank current line (including newline) yy
Vim composer Normal Paste system clipboard text at cursor p
Vim composer Normal Insert before / append after current grapheme i / a
Vim composer Normal Return to chat (draft kept) Esc
Vim composer Insert Return to Normal Esc
Reaction picker Move / confirm j/k or Up/Down arrows / Enter
Media viewer Previous / next h/l or arrows
Media viewer Save image or video as a file s opens folder picker; j/k or Up/Down selects, h/Left goes up, l/Right opens folder, / filters folders; Enter edits basename, Enter saves; Esc leaves search/editing before closing

In an editable Chats/Communities composer (including Vim Insert and message editing), terminal paste inserts the complete text block at the cursor, preserving line breaks without sending. Press Enter separately to submit. Bracketed paste is enabled only while that composer owns editable input; search and other screens keep their existing input behavior. If the terminal delivers Ctrl+V as a key instead, the existing clipboard text/file/image handling still applies.

Save As starts in the app's current working directory. Browse folders in the viewer, then edit the separate proposed basename and confirm. The extension is displayed but fixed from the source media format (or a kind-based fallback). The basename must be a single component, not a path. Folder search filters names; Esc retains the filter while returning to browsing, and entering a folder clears it. Esc in name editing returns to browsing; Esc in browsing closes Save As. The viewer shows the saved destination after success. Existing files are never overwritten; choose another name if one exists.

The optional Vim composer starts in Normal mode; its border title shows Normal or Insert. i enters Insert at the current cursor; a advances past the current grapheme within the same line before entering Insert (and stays put at the end of a line or an empty draft). Ordinary i composition remains unchanged. These motions move only the cursor: a word separates letters/digits/underscores from punctuation, while a WORD is any non-whitespace run. In Normal mode, y waits for a supported motion or another y; Esc cancels it. Yanks copy to the system clipboard, without changing the draft or cursor. In Normal mode, p inserts the clipboard's text at the cursor, even after yy; it does not use a Vim register or Vim's after-cursor/linewise put positioning. p does not attach images or files; use Ctrl+V while editing to paste those. There are no registers or counts, and this is not full Vim emulation. Search, substitution, and deletion are not available here. Files pasted with Ctrl+V are queued as attachments; text becomes the caption of the first attachment.

Queued images (including clipboard images) and videos show compact still previews while composing, before you send. Up to three previews are prepared at a time; video frames require FFmpeg with seekable fd: input support. The preview reads the selected local file without changing it or creating JPEG sidecars. Filenames remain the fallback for missing, corrupt, unsupported, or failed media. On small terminals, previews and attachment labels give way to the text and cursor; additional attachments may be summarized. Sending and captions are unchanged.

Development

Runtime performance diagnostics

The opt-in profiler is disabled unless WPTUI_PERF=1. Build and run the release binary with the exact command WPTUI_PERF=1 target/release/wp-tui, reproduce the CPU spike or interaction, and exit normally. It writes one bounded report to ~/.cache/wptui/perf-report.txt.

To build and test without using local Cargo resources, see cloud-built preview binaries. Push a preview/** branch based on main when you want a downloadable Linux binary without creating a release.

For contributors who prefer local checks, run the Rust test suite:

cargo test -- --test-threads=1

Run the Go test suite:

cd whatsrust/lib
go test ./...

Continuous integration runs format checks, Rust and Go builds/tests, and installer archive tests on both Linux and macOS for pushes to main and pull requests. Nix build and dev-shell checks run on Linux. For on-demand feature binaries, start a preview/** branch from main; its pushes run preview checks and upload a Linux binary. To build the integrated main on demand, manually dispatch release.yml on main: it uploads artifacts without publishing a release. Tagged releases remain a separate decision.

Disclaimer

wptui is an unofficial, experimental client. It is not affiliated with, endorsed by, or associated with WhatsApp or Meta Platforms, Inc. Unofficial clients operate in a terms-of-service gray area; use at your own risk, as an account restriction is possible.

License

MIT © 2026 andiveli. See LICENSE.

Third-party components are listed in THIRD_PARTY_NOTICES.md.

About

Keyboard-driven WhatsApp client for the terminal (Rust/Ratatui + Go/whatsmeow)

Topics

Resources

Contributing

Stars

203 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages