A fast, keyboard-driven TUI for WhatsApp Web. Live next to vim and tmux — not in another Electron window eating your RAM.
$npm i -g @gtchakama/wa-tui
Every feature earns its keybinding.
j/k to move, ⏎ to open, Ctrl+K to search. Your hands never leave home row.
Pure Node + neo-blessed. Boots in under a second. No Electron, no fan noise.
One modal. Search across all chats or scope to the current thread's history. Incremental, case-insensitive.
Images, voice notes, documents — downloaded straight into your working directory. Ready for scp or mv.
Press F2 to preview live. Settings persist under ~/.wa-tui/. Matches your dotfiles, not the other way round.
The QR renders in the terminal itself — ASCII or kitty graphics if your emulator supports it. Zero browser tabs.
Needs Node 18+ and Chrome (or Chromium) on PATH.
One global install via npm. Homebrew tap also available.
$ npm i -g @gtchakama/wa-tui
Run from the directory where you want session files stored.
$ wa-tui
Phone → Linked devices → scan. Persists across reboots.
↑↓ browse ⏎ open Ctrl+K find
Honest about what it's for. (And what it isn't.)
A ping lands, you glance a pane over, reply, and you're back in vim. No Alt-Tab into a 500MB chat app, no phone pickup that turns into 20 min of scrolling.
Runs happily on a dev server or VPS. Read WhatsApp wherever you have a shell — handy when your phone is across the room or locked in a drawer.
No Electron, no persistent browser window. Boots in under a second and idles cheap on hardware that Slack would melt.
Downloads land in the current working directory. cd into a repo, grab the asset a client sent, and it's already next to your code. No Downloads graveyard.
No stories, no status, no ads, no nudges. Just text and a keyboard. The UI has nothing to sell you, so it doesn't try.
If you already think in j/k/⏎/Ctrl+K, this is the fastest WhatsApp client you'll ever use. Fuzzy-find across all chats + current thread beats scrolling, every time.
Plain Node. No build step. Every file does one thing and does it clearly.
# Clone, install, run — that's the whole dev loop
git clone https://github.com/gtchakama/wa-tui.git
cd wa-tui
pnpm install # or: npm install
pnpm start # scans QR, drops you into the TUI
# Run the test suite
node --test
// src/whatsapp/service.js — every phase is an event you can hook
this.client.on('qr', (qr) => {
this.emit('lifecycle', { phase: 'qr' });
this.emit('qr', qr);
});
this.client.on('loading_screen', (percent, message) => {
this.emit('lifecycle', { phase: 'syncing', percent, message });
});
this.client.on('ready', () => {
this.emit('lifecycle', { phase: 'ready' });
});
this.client.on('auth_failure', (msg) => {
this.emit('lifecycle', { phase: 'auth_failure', message: msg });
});
// First-run Chrome install with live progress — no silent hangs
async function installBrowser(onProgress) {
cleanStaleChromeCache();
const { install, detectBrowserPlatform, Browser } = require('@puppeteer/browsers');
const { PUPPETEER_REVISIONS } = require('puppeteer-core/lib/cjs/puppeteer/revisions.js');
await install({
browser: Browser.CHROME,
buildId: PUPPETEER_REVISIONS.chrome,
platform: detectBrowserPlatform(),
cacheDir: path.join(os.homedir(), '.cache', 'puppeteer'),
downloadProgressCallback: (downloaded, total) => {
if (total > 0) onProgress(Math.round((downloaded / total) * 100));
},
});
}
// Vim-flavored keybindings everywhere. Want your own? PRs welcome.
screen.key(['j', 'down'], () => chatList.down(1));
screen.key(['k', 'up'], () => chatList.up(1));
screen.key(['enter'], () => openChat(chatList.selected));
screen.key(['C-k', '/'], () => openFuzzyFinder());
screen.key(['1', '2', '3'], (ch) => filter(ch)); // all / DMs / groups
screen.key(['F2'], () => openPaletteSettings());
screen.key(['q', 'C-c'], () => process.exit(0));
Actual code from main. No transpilation, no pseudocode.
A few thousand lines of JavaScript. No TypeScript build. No webpack. No drama.
The surface area is tiny — a feature PR lands in days, not months. Great first open source contribution if you've been looking for one.
# fork → branch → ship gh repo fork gtchakama/wa-tui --clone cd wa-tui git checkout -b feat/my-idea pnpm install pnpm start # try it live node --test # keep the suite green gh pr create --fill
Two contributors, many late nights, equal commits.
Want your avatar on this page? Send a PR — first-time contributors especially welcome.
Open source under ISC. If it saves you from one Electron app, consider starring it.
Star on GitHub