whatat

WhatsApp for your terminal — fast, keyboard-driven, and built for developers.

A full-featured terminal UI (TUI) client powered by whatsapp-web.js and OpenTUI. Chat, send media, update your status, and manage conversations without leaving the command line.

Features · Installation · Usage · Keyboard Shortcuts · Configuration · Troubleshooting · Project Structure

---

Overview

whatat brings WhatsApp to your terminal with a polished, keyboard-first interface. It connects through WhatsApp Web (Linked Devices), persists your session locally, and renders chats, images, and status updates directly in the terminal.

Designed for developers and power users who live in the terminal and want a lightweight alternative to the desktop app — without sacrificing core messaging features.

Features

Messaging

• Real-time chat — Send and receive messages with delivery/read receipts (✓ / ✓✓)
• Chat search — Filter conversations by name or last message (Ctrl+F)
• Message history — Initial fast load with automatic background pagination for older messages
• Group chats — Color-coded sender names per participant
• Reply previews — Quoted/replied messages shown inline
• Reactions — Emoji reactions displayed on messages
• Day separators — Today, Yesterday, and date labels between message groups

Media & Rich Content

• Inline images — Photos and stickers rendered in-terminal via framebuffer
• Image sending — Attach local images by file path (Ctrl+I)
• Media labels — Videos, audio, voice notes, documents, and stickers show descriptive placeholders when inline rendering isn't possible

Terminal UX

• Keyboard-first navigation — Three-pane layout: sidebar → messages → input
• Emoji picker — Quick emoji insertion (Ctrl+E)
• Status updates — Set your WhatsApp About/status text (Ctrl+S)
• Live header — Connection indicator and clock
• Help overlay — Press ? anytime for shortcuts

Session & Reliability

• QR login — Scan once via WhatsApp → Linked Devices; session saved locally
• High-res QR fallback — Auto-opens scannable PNG in your system image viewer
• Single-instance lock — Prevents profile/browser conflicts between runs
• Auto browser detection — Finds Chrome, Edge, or Chromium on Windows, macOS, and Linux

---

Requirements

Requirement	Notes
Bun ≥ 1.0	Recommended runtime
Chrome / Edge / Chromium	Headless browser for WhatsApp Web
Terminal with true-color support	Recommended for image rendering

Node.js is not required when using Bun. Puppeteer (via whatsapp-web.js) handles browser automation under the hood.

---

Installation

1. Clone the repository

git clone https://github.com/mine3krish/whatat
cd whatat

2. Install dependencies

bun install

3. Start the client

bun start

On first launch, scan the QR code with WhatsApp → Linked Devices → Link a Device. Your session is saved in .wwebjs_auth/ for subsequent runs.

---

Usage

Development mode

Run with file watching for live reload during development:

bun dev

Prefer bun start for normal use. Hot reload can spawn duplicate browser instances and trigger profile lock errors.

First-time login

1. Run bun start
2. A QR code appears in the terminal and opens in your default image viewer
3. Scan with your phone
4. Chats load automatically once connected

Press Ctrl+O to re-open the QR image if needed.

Sending messages

1. Tab to the chat list and select a conversation
2. Tab to the message input
3. Type your message and press Enter
4. Use Ctrl+E for emojis or Ctrl+I to send an image

---

Keyboard Shortcuts

Shortcut	Action
Tab / Shift+Tab	Cycle sidebar → messages → input
Ctrl+F	Focus chat search
↑ ↓	Navigate chat list
Enter	Open chat / send message / pick emoji
Ctrl+↑ / PgUp	Load older messages
Ctrl+E	Open emoji picker
Ctrl+I	Send image from file path
Ctrl+S	Set WhatsApp status
Ctrl+R	Refresh chat list
Ctrl+L	Log out
Ctrl+O	Open login QR in image viewer
?	Toggle help overlay
Esc	Close overlay / navigate back
Ctrl+C	Quit

---

Configuration

Environment variables

Variable	Description
CHROME_PATH	Absolute path to Chrome/Edge/Chromium executable
PUPPETEER_EXECUTABLE_PATH	Alternative to CHROME_PATH (Puppeteer convention)

Windows (PowerShell)

$env:CHROME_PATH = "C:\Program Files\Google\Chrome\Application\chrome.exe"
bun start

macOS / Linux

export CHROME_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
bun start

Session data

Path	Purpose
.wwebjs_auth/	WhatsApp session and auth tokens
.wwebjs_auth/whatat.pid	Single-instance process lock
.wwebjs_auth/login-qr.png	Latest login QR (for external scanning)

All session paths are gitignored. Delete .wwebjs_auth/ to force a fresh login.

---

Troubleshooting

Could not find Chrome version

Install Google Chrome or Microsoft Edge, then set the browser path explicitly:

# Windows
$env:CHROME_PATH = "C:\Program Files\Google\Chrome\Application\chrome.exe"
bun start

The browser is already running

Another whatat instance or a stuck headless Chrome process is holding the profile lock.

1. Close all other whatat terminals
2. Kill stray Chrome/Edge processes (Task Manager on Windows, pkill chrome on Linux)
3. Remove the lock file: .wwebjs_auth/whatat.pid
4. Restart with bun start (not bun dev)

QR code won't scan

• The terminal QR uses black-on-white for contrast
• A high-resolution PNG is saved to .wwebjs_auth/login-qr.png and opened automatically
• Press Ctrl+O to re-open it in your image viewer
• Ensure your terminal window is wide enough for the inline QR fallback

Messages not loading

• Wait for the header to show ● online
• Switch to another chat and back
• Press Ctrl+R to refresh chats
• Use Ctrl+↑ / PgUp to manually fetch older messages
• Check that WhatsApp Web is working in a regular browser

Images fail to render

• Ensure your terminal supports true-color / RGB rendering
• Large images are downscaled automatically; very small or corrupt media shows a [image] fallback
• Videos and documents display as labeled placeholders (not playable in-terminal)

---

Project Structure

whatat/
├── src/
│   ├── app/
│   │   └── App.tsx              # Root layout, keyboard routing, lifecycle
│   ├── components/
│   │   ├── AttachImage.tsx      # Image send overlay
│   │   ├── ChatList.tsx         # Sidebar with search + chat select
│   │   ├── HelpOverlay.tsx      # Shortcut reference
│   │   ├── MessageBubble.tsx    # Individual message rendering
│   │   ├── MessageInput.tsx     # Compose bar + emoji panel
│   │   ├── MessagePanel.tsx     # Thread view + pagination
│   │   ├── QrLogin.tsx          # QR login screen
│   │   ├── StatusEditor.tsx     # WhatsApp status editor
│   │   └── TerminalImage.tsx    # Framebuffer image renderer
│   ├── state/
│   │   └── app-store.ts         # SolidJS signals + message store
│   ├── utils/
│   │   ├── emojis.ts            # Quick emoji list
│   │   ├── format.ts            # Time, ack, date helpers
│   │   ├── image.ts             # Sharp decode + QR generation
│   │   ├── message-content.ts   # Message type labels
│   │   └── theme.ts             # Color palette
│   ├── whatsapp/
│   │   ├── browser.ts           # Chrome/Edge auto-detection
│   │   ├── service.ts           # whatsapp-web.js client wrapper
│   │   ├── session-lock.ts      # PID lock + stale lock cleanup
│   │   └── types.ts             # Shared TypeScript interfaces
│   └── index.tsx                # Entry point
├── package.json
└── README.md

---

Tech Stack

Layer	Technology
Runtime	Bun
Language	TypeScript
UI framework	SolidJS
Terminal renderer	OpenTUI (@opentui/core, @opentui/solid)
WhatsApp bridge	whatsapp-web.js
Browser automation	Puppeteer (transitive)
Image processing	Sharp
QR generation	qrcode

---

Disclaimer

This project is not affiliated with, endorsed by, or connected to WhatsApp or Meta.

whatat uses unofficial WhatsApp Web automation via whatsapp-web.js. Using third-party clients may violate WhatsApp's Terms of Service and carries the risk of account restrictions. Use at your own discretion — preferably with a secondary number or test account.

---

Contributing

Contributions are welcome. To get started:

1. Fork the repository
2. Create a feature branch: git checkout -b feat/my-feature
3. Make your changes and test with bun start
4. Open a pull request with a clear description

Please keep changes focused and match the existing code style.

---

License

MIT © whatat contributors

---

Built with ☕ for terminal lovers.

If you find this useful, consider giving it a ⭐ on GitHub.