--- type: overview title: Quickstart description: What the wh WhatsApp terminal client with per-chat and global AI autoreply (system prompt in SOUL.md, reply delay, image descriptions) and optional web control panel does, how to build and run it, and where to find each topic in this wiki. tags: [overview, quickstart, rust, whatsapp, tui, ai, web-panel] sources: - id: openwiki-source-651d1fb6c9e49916a916ab51 resource: repo://Cargo.toml - id: openwiki-source-9fec9d1af408501c9c455161 resource: repo://src/app.rs - id: openwiki-source-043e6252badc57a1ee6bfb48 resource: repo://src/autoreply.rs - id: openwiki-source-2a737474d86fc75cc9d9694f resource: repo://src/config.rs - id: openwiki-source-b55a21a31ede1b56cd31a6a6 resource: repo://src/main.rs generated: { by: "claude-code", at: "2026-10-21T21:49:12.291Z" } verified: - by: openwiki/0.7.2 at: 2026-10-21T21:49:12.291Z --- # Quickstart `wh` (`Cargo.toml:1-5`) is a Rust terminal client for WhatsApp. It links as a companion device by QR code, shows chats and contacts in a [ratatui](architecture/terminal-ui.md) interface, stores messages locally in SQLite and can answer incoming messages automatically with an OpenAI-compatible model — chat by chat or for all chats at once — in private chats and in groups (broadcasts, status and newsletters excluded). An optional [web control panel](integrations/web-control-panel.md) lets a browser toggle the autoreplies and stop the bot. ## Build and run ```sh cargo build --release cargo run --release cargo test ``` The crate uses edition 2024. `whatsapp-rust` is built with `default-features = false` because its default `simd` feature needs nightly (`Cargo.toml:8-10`). The release profile strips symbols and uses LTO with a single codegen unit (`Cargo.toml:27-33`). `[lints.rust] linker_messages = "allow"` (`Cargo.toml:35-37`) silences the informational MSVC linker line printed because the binary exports symbols. `wh --version` (or `-V`) prints `wh ()` and exits; the same version is shown at the bottom right of the main screen (`src/main.rs:24-41`, `build.rs`). On first start the app shows a QR code: scan it from WhatsApp → *Linked devices*. The session is kept in `session.db`, so later starts connect directly. Main keys: `Tab` switches list/input, `Enter` opens a chat or sends, typing in the list filters it, `PgUp`/`PgDn`/`Home`/`End` move through the list, `F2` chats/contacts, `F3` toggles autoreply for the open chat, `F4` toggles the global autoreply ("AI tutte"), `Canc` twice deletes the selected chat locally, `F10` quits ([key bindings](architecture/app-state.md#key-bindings)). ## Configuration in short Settings live in `config.toml` inside the data directory `/wh` (on Windows `%APPDATA%\wh`, on Linux `~/.config/wh`), next to `session.db` and `history.db` (`src/config.rs:46-58`, `src/config.rs:160-168`); the repository's `config.toml.global.template` lists every key. The system prompt is not a key: it is the file `SOUL.md` in the same folder (start from `soul.md.template`), and the optional `vision.md` replaces the built-in request used to describe images. The two databases are separate by design: `session.db` is the WhatsApp library's session and key store, `history.db` holds the app's chats, messages, autoreply flags and image descriptions. Without `openai_api_key` and a non-blank `SOUL.md` the app still runs as a plain WhatsApp client. Optional keys tune the reply delay (`reply_delay_seconds`), the startup catch-up (`catch_up_seconds`), AI retries (`ai_retries`), the vision model (`openai_vision_model`), an AI request log (`ai_log`, written to `ai_requests.log` in the same folder) and the web panel port (`web_port`, unauthenticated, all interfaces). The old keys `system_prompt`, `cooldown_seconds` and `group_cooldown_seconds` are ignored. Keys and defaults: [Configuration and data](operations/configuration-and-data.md). ## Autoreply in one paragraph The first unanswered message of an enabled chat starts a `reply_delay_seconds` wait; messages arriving meanwhile join the same reply. Images are described once by the vision model and only their descriptions reach the AI. The reply is dropped if the owner answered by hand, and the model can stay silent by calling the `no_reply` tool, whose use is decided by `SOUL.md`. Details: [AI auto-reply workflow](workflows/ai-autoreply.md). ## Startup in one line `main` prints the version and exits for `--version`; otherwise it loads the config, opens the history, starts the WhatsApp client, the optional web panel and an input thread, then runs the draw/receive loop until quit (`src/main.rs:36-64`, see [Runtime and event loop](architecture/runtime-and-event-loop.md)). ## Where to look | Task | Page | Source | |---|---|---| | Startup, version flag, channels, threads, main loop | [Runtime and event loop](architecture/runtime-and-event-loop.md) | `src/main.rs`, `build.rs` | | Events, state, keys, filter, chat deletion, reply orchestration, background tasks | [Application state](architecture/app-state.md) | `src/app.rs` | | Screens, rendering, message formatting, footer version | [Terminal UI](architecture/terminal-ui.md) | `src/ui.rs` | | WhatsApp session, events, JIDs, media | [WhatsApp client](integrations/whatsapp-client.md) | `src/whatsapp.rs` | | AI HTTP requests, `no_reply` tool, image descriptions, retries, errors | [AI client](integrations/ai-client.md) | `src/ai.rs` | | Web control panel: routes, security, browser page | [Web control panel](integrations/web-control-panel.md) | `src/web.rs`, `src/web_page.html` | | When and how the AI replies (global/per-chat, groups, reply delay, owner-answered drop, images, catch-up, context) | [AI auto-reply workflow](workflows/ai-autoreply.md) | `src/autoreply.rs`, `src/app.rs` | | Local SQLite messages, chats, contacts, settings, image descriptions | [History store](concepts/history-store.md) | `src/history.rs` | | Config keys, `SOUL.md` / `vision.md`, data dir, security notes | [Configuration and data](operations/configuration-and-data.md) | `src/config.rs` | | Test suites and how to run them | [Unit tests](testing/unit-tests.md) | `src/*.rs` |