WhatsApp in your terminal.

⚠️ Beta - This project is under active development. Some features may be incomplete or change between releases.

A beautiful Terminal User Interface for WhatsApp using WAHA (WhatsApp HTTP API). Manage your WhatsApp sessions, chats, and messages directly from your terminal with an intuitive TUI powered by OpenTUI.

• 📱 Session Management - Create, view, and manage WAHA sessions with QR code or phone number pairing
• 💬 Chat Interface - Browse chats with WhatsApp-style layout and real-time updates
• ✉️ Messaging - Send and receive messages with read receipts, (edited) indicators, and auto-history loading
• 📊 Interactive Polls - View and vote in polls with real-time result progress bars (█░)
• 🔗 Link Previews - Rich metadata rendering for URLs (title, description, domain) directly in the chat
• 🔍 Search & Filters - Filter chats by all, unread, favorites, groups, or labeled with instant global and in-chat search
• 📋 Context Menus - Right-click style menus for chats (archive, delete, mark unread, pin, mute) and messages (star, pin, react, forward, delete)
• ⚙️ Settings - Configurable notification preferences, enter-to-send, and background sync
• 🔔 Desktop Notifications - Native OS notifications for messages and calls with per-category controls
• ⏱️ Disappearing Messages - Visibility indicators for chats with disappearing mode enabled
• 🔄 Real-Time Updates - WebSocket-powered live updates for messages, reactions, polls, labels, and typing indicators
• 🆕 Update Checker - Automatic notification when a new version is available

bunx @muhammedaksam/waha-tui

bun add -g @muhammedaksam/waha-tui
waha-tui

git clone https://github.com/muhammedaksam/waha-tui.git
cd waha-tui
bun install
bun dev

• Bun >= 1.0
• A running WAHA server

If you're using the WEBJS engine (default for WAHA CORE), you must enable tagsEventsOn in your session config to receive typing indicators (presence.update) and message ack events:

{
  "name": "default",
  "config": {
    "webjs": {
      "tagsEventsOn": true
    }
  }
}

Note: This setting is required for real-time typing indicators to work. See WAHA documentation for more details.

On first run, WAHA TUI will prompt you for configuration with a beautiful setup wizard.

Configuration is stored in $XDG_CONFIG_HOME/waha-tui/ (defaults to ~/.config/waha-tui/) with secrets separated from metadata:

# WAHA TUI Configuration
# Connection settings for WAHA server

WAHA_URL=http://localhost:3000
WAHA_API_KEY=your-api-key-here

{
  "version": "1.6.1",
  "createdAt": "2024-12-19T00:00:00.000Z",
  "updatedAt": "2024-12-19T00:00:00.000Z",
  "settings": {
    "enterIsSend": true,
    "messageNotifications": {
      "showNotifications": true,
      "showReactionNotifications": false,
      "playSound": true
    },
    "groupNotifications": {
      "showNotifications": true,
      "showReactionNotifications": false,
      "playSound": true
    },
    "statusNotifications": {
      "showNotifications": false,
      "showReactionNotifications": false,
      "playSound": false
    },
    "showPreviews": true,
    "backgroundSync": true
  }
}

For development, you can also create a .env in the project root which takes precedence:

WAHA_URL=http://localhost:3000
WAHA_API_KEY=your-api-key-here

⚠️ The q key in Sessions view performs a destructive action: it logs out and deletes the current session.

Enable debug logging to troubleshoot issues:

# Via environment variable
WAHA_TUI_DEBUG=1 bun dev

# Via command-line flag
bun dev --debug

Debug logs are saved to $XDG_CONFIG_HOME/waha-tui/debug.log with automatic sanitization of sensitive data.

See DEVELOPMENT.md for development setup, commands, and project structure.

• Runtime: Bun
• UI Framework: OpenTUI
• WAHA SDK: @muhammedaksam/waha-node
• TypeScript: Type-safe development

See CONTRIBUTING.md for development setup and guidelines.

See SECURITY.md for security policy and reporting vulnerabilities.

This project is licensed under the MIT License - see the LICENSE file for details.

• WAHA HTTP API - WhatsApp HTTP API
• WAHA Node SDK - TypeScript SDK for WAHA
• OpenTUI - Terminal UI framework used by waha-tui