🤫 whisperlan — terminal whispers for your LAN

Same WiFi. No server. No account. Just type.

whisperlan turns every laptop on your local network into a chatroom — plus encrypted 1-on-1s. One Python file, zero dependencies, macOS + Linux. The command stays short: type whisper (or whisperlan, same thing).

🎥 That's a static mock. To record a real demo: brew install vhs (or asciinema), run two whisper --name … sessions side by side, export to docs/demo.gif, and swap the image link above. Real typing demos convert 10x better than mockups.

┌─────────────────────────────────────────────────┐
│ 🤫 whisper │ room: lan │ 3 online               │
│ type + enter to send │ /p @name private │ /help │
│ 12:01 ali            yo who is here??           │
│ 12:01 bob            present 🫡                 │
│ ── cara joined from 192.168.1.42 🔒 ──          │
│ 🔒→bob  secret plan at midnight_                │
│──────────────────────┼─ ● ONLINE ───────────────│
│ 🔒→bob secret plan…  │ ➤ #lan (room)            │
└──────────────────────┴──────────────────────────┘

Option A — Homebrew 🍺 (easiest on Mac):

brew tap Tarraf2020/whisperlan https://github.com/Tarraf2020/whisperlan && brew install Tarraf2020/whisperlan/whisperlan

Upgrades later with brew upgrade whisperlan.

Option B — one-liner:

curl -fsSL https://raw.githubusercontent.com/Tarraf2020/whisperlan/main/install.sh | bash

Option C — clone:

git clone https://github.com/Tarraf2020/whisperlan.git
cd whisper
./install.sh

Option D — pip:

pip install git+https://github.com/Tarraf2020/whisperlan.git

Forked it or renamed your repo? Set REPO=you/name: curl -fsSL ... | REPO=you/name bash Don't forget to replace Tarraf2020/whisperlan in this README + pyproject.toml with your repo path.

Requires: Python 3.8+ (stdlib only — curses, socket, ssl). No packages to install.

Just re-run the installer (it overwrites + keeps your name/history):

curl -fsSL https://raw.githubusercontent.com/Tarraf2020/whisperlan/main/install.sh | bash

No need to check manually — whisperlan tells you inside the app: a 🔔 line appears when a peer runs a newer version, or when GitHub has one (checked max once a day, silent when offline).

whisperlan --name ali
# short alias works too:
whisper --name ali

Friend on the same WiFi, same port:

whisper --name bob

You auto-discover each other in ~5 seconds. Flags: -n = name, -p = room port, --pport = private port, -v = version.

Mention with @name in the room → they get a notification. Sidebar shows (2) unread badges for privates.

Privates, DMs, and @you mentions pop a real desktop banner — not just a terminal beep:

• Warp: uses Warp's native notification hook (OSC 777), works out of the box. If you also want a sound, enable it in Warp: Settings > Features > Terminal > Audible terminal bell (+ macOS System Settings > Notifications > Warp).
• Other terminals: Ghostty/iTerm2/Kitty/WezTerm banner via OSC 9 + audible BEL (OSC-only by default, click focuses the terminal). Fallback osascript (macOS) / notify-send (Linux) only when the terminal likely lacks OSC 9 (e.g. Apple Terminal). Force with WHISPER_NATIVE=on (dual) or WHISPER_NATIVE=off (OSC-only).
• Toggle anytime inside the app: /notify off (mute), /notify on. Or permanently: WHISPER_NOTIFY=off whisper --name ali.

• Room = encrypted mesh 🔒: one TLS-encrypted TCP unicast per peer, never broadcast. Passive sniffers see connection metadata at most, never content. Needs v1.5.0+ on both ends — old peers are skipped with a warning.
• Private = direct TLS-encrypted TCP to one peer (port+1 by default, auto-bumped if busy). Cert self-generates once via system openssl → ~/.whisper-cert.pem. Passive sniffers see gibberish.
• Presence stays public: hello / heartbeat / bye / typing are still plaintext broadcast (nick + IP + ports, no chat content). A sniffer sees who's online, not what they say.
• Honest limit: self-signed = TOFU, no CA, so a skilled active LAN attacker could MITM. No openssl on the machine = plain-TCP fallback (still unicast, still sniffable). Don't send bank passwords. 😉

Packet shape: JSON {v, id, type, from, uid, to?, text, ts, ip, pport, mesh?}, types hello / heartbeat / bye / msg / dm / typing / rename / me / priv / priv-typing / room / room-me (msg/me/dm = legacy ≤1.4.x receive path only). Heartbeat 5s, timeout 15s. No chat history is written to disk — quit and the session is gone.

• whisper: command not found → open a NEW terminal (picks up ~/.local/bin on PATH), or export PATH="$HOME/.local/bin:$PATH".
• Nobody sees me → same WiFi? (guest networks isolate clients), same --port? firewall allowed the UDP popup?
• Solo test → two terminals: whisper --name ali + whisper --name bob.
• Weird characters → use iTerm2 / Ghostty / Kitty / Terminal.app.
• Uninstall → ./uninstall.sh.

If whisper made your LAN party better, fuel the next feature:

• Hit ⭐ Star + GitHub Sponsor (button at the top, via .github/FUNDING.yml)
• Or Ko-fi: whisperlan (placeholder — swap in your real link)

Maintainer: after git push, go to github.com → your repo → Settings → Sponsors (or ko-fi.com) and replace Tarraf2020 / whisperlan in .github/FUNDING.yml with your real handles, or the button goes nowhere.

PRs welcome! Keep it: one file, zero deps, works on fresh macOS Python. Run a syntax check before pushing:

python3 -m py_compile whisper.py

Ideas wanted: file drop (/send), emoji reactions, internet relay mode, Windows support.

MIT — see LICENSE. Do whatever you want, just keep the notice.

Made for LAN parties, classrooms, hackathons & dorm rooms. If it made your table laugh, leave a ⭐.