explaingit

he4rt/wpp-tui

★ 15TypeScriptAudience · developerComplexity · 4/5ActiveLicenseSetup · moderate

TLDR

Terminal WhatsApp client built on Baileys and Ink, with chat, stats, and debug tabs, plus a structured JSON logger and optional webhook proxy.

Mindmap

mindmap
  root((wpp-tui))
    Inputs
      WhatsApp QR pairing
      Baileys socket events
      WEBHOOK_URL env
    Outputs
      ASCII chat UI
      Dated JSON logs
      Extracted payloads
    Use Cases
      Use WhatsApp from terminal
      Archive group history
      Forward events to webhook
    Tech Stack
      Node.js
      TypeScript
      Baileys
      Ink
      React
      Python

Things people build with this

USE CASE 1

Run a keyboard-only WhatsApp client inside a terminal window over SSH

USE CASE 2

Archive every WhatsApp event into dated JSON logs and extract clean per-entity files

USE CASE 3

Forward all WhatsApp events to a webhook for a bot or analytics pipeline

USE CASE 4

Decrypt and inspect WhatsApp polls per voter for moderation or research

Tech stack

Node.jsTypeScriptBaileysInkReactPython

Getting it running

Difficulty · moderate Time to first run · 30min

Needs Node.js 24+, pnpm, and Python 3 for payload extraction; uses the unofficial Baileys library so account bans are a real risk.

ISC lets you use, copy, and redistribute the code for any purpose as long as the copyright notice stays.

In plain English

wpp-tui is a WhatsApp client that runs entirely inside a terminal window rather than as a graphical app. To make this work it pairs two libraries: Baileys, an unofficial WhatsApp socket implementation in Node.js, and Ink, which lets developers build terminal interfaces using React components. The result is a text-based UI where boxes, lists, and message feeds are drawn with line characters, and the chat layout looks similar to a normal messenger app rendered in ASCII art. Getting started involves installing dependencies with pnpm and running pnpm dev. On first launch the user scans a QR code with the Linked Devices feature in WhatsApp, and the session is reused on later runs. The interface has three tabs that the user cycles through with Tab or slash commands. The Chat tab shows a sidebar of groups marked with a hash and direct messages marked with an at sign, along with an auto-scrolling message feed. The Stats tab draws a bar chart of top senders and a breakdown of message types. The Debug tab shows a live stream of incoming events with scroll support and connection details. The tool also acts as a structured logger. Every WhatsApp event, including message upserts, delivery updates, reactions, presence changes, group member tag changes, and credential updates, is persisted to dated JSON files under a logs directory. A make extract-payload command then parses those raw logs into more useful files, such as messages.json, users.json, groups-full.json, reactions.json, threads.json, polls.json, member-profiles.json, activity.json, stickers.json, receipts.json, presence.json, a unified timeline.json, and a stats.json summary. Polls are decrypted using AES-256-GCM and HMAC-SHA256 so that individual votes are visible per user. An optional webhook proxy can forward every event to an external URL by setting a WEBHOOK_URL environment variable before starting the dev script. Keyboard shortcuts are documented for tab cycling, chat navigation, and quitting. The project structure listing shows source files for the Ink components, a hook that wraps the Baileys socket, and a Python script for the payload extraction step. The tech stack is Node.js 24 or newer, Baileys 7, Ink 7 with React 19, tsup for builds, pino for logging, and Python 3 for extraction. The license is ISC.

Copy-paste prompts

Prompt 1
Install wpp-tui with pnpm, run pnpm dev, and pair it with my phone by scanning the QR code
Prompt 2
Set WEBHOOK_URL before starting wpp-tui and write a small Node receiver that logs every forwarded event
Prompt 3
Run make extract-payload in wpp-tui and explain what each output file like messages.json and timeline.json contains
Prompt 4
Walk me through the Ink component layout that powers the Chat, Stats, and Debug tabs in wpp-tui
Prompt 5
Show how wpp-tui decrypts polls with AES-256-GCM and HMAC-SHA256 to expose per-user votes
Open on GitHub → Explain another repo

Generated 2026-05-22 · Model: sonnet-4-6 · Verify against the repo before relying on details.