Flow.Launcher.Plugin.Beeper

Search Beeper Desktop chats from Flow Launcher and jump straight into a conversation.

This plugin queries the local Beeper Desktop API (the HTTP server Beeper exposes on 127.0.0.1:23373 when its developer toggle is on) and surfaces your unified inbox inside Flow Launcher. Type the action keyword, see your most recent chats with their network and avatar, press Enter on one, and Beeper Desktop focuses that conversation.

Table of Contents

• Security
• Install
• Usage
• API
• Maintainers
• Contributing
• License

Security

This plugin stores a Beeper Desktop API access token in Flow Launcher's plugin settings file, under:

%APPDATA%\FlowLauncher\Settings\Plugins\Beeper\Settings.json

The token grants full read/write access to every chat account connected to your Beeper Desktop instance. Treat it like a password:

• Do not commit Settings.json to source control.
• The default Beeper Desktop API binds to 127.0.0.1 only. Do not enable Remote Access (Settings → Developers → Advanced) unless you understand the exposure.
• Revoke the token at any time from Beeper → Settings → Developers → Approved connections.

The plugin only makes outbound HTTPS-less requests to the local loopback API (http://127.0.0.1:23373 by default) and never transmits the token elsewhere.

Install

Prerequisites

• Beeper Desktop 4.1.169 or newer with the local API enabled (see Usage).
• Flow Launcher (its bundled embeddable Python is used at runtime; no system Python is needed just to use the plugin).
• mise, only if you're installing from source (see Option B) — used to fetch a Python matching Flow Launcher's embeddable interpreter, since that embeddable Python ships without pip and can't install packages itself.

Option A — Plugin Manager (recommended once published)

Open Flow Launcher and run:

pm install Beeper

Then jump to Configuring the token.

Option B — Manual install from source

1. Clone or download this repository.
2. Install dependencies and deploy the plugin using the mise tasks:

mise install
mise run deploy

mise install reads mise.toml and fetches a Python 3.11 build if you don't already have one, without touching any other Python version on your machine. mise run deploy then:

• installs the dependencies from requirements.txt into lib/ using that pinned interpreter (mise run install-deps, run automatically as a dependency of deploy) — this matters because one of requests' dependencies (charset_normalizer) ships a compiled extension, which must match Flow Launcher's embeddable Python's version and architecture (currently 3.11, 64-bit) or the plugin will fail to load with an ABI mismatch;
• copies (via scripts/deploy.ps1) the whole plugin folder as a real copy into %APPDATA%\FlowLauncher\Plugins\Flow.Launcher.Plugin.Beeper.

Do not symlink the plugin folder into Flow Launcher's Plugins directory instead of copying it. flox-lib resolves the plugin's path to its real, symlink-following target when detecting the Flow Launcher installation — if that target lives outside ...\FlowLauncher\Plugins\... (e.g. your clone of this repo), detection fails with FileNotFoundError: Unable to locate Launcher directory, even though the plugin runs fine otherwise. Re-run mise run deploy after each change instead.

3. Restart Flow Launcher (right-click the tray icon → Exit, then relaunch).

Dependencies

Declared in requirements.txt:

• flox-lib — Flow Launcher JSON-RPC helper.
• requests — HTTP client for the Beeper Desktop API.

Usage

Enabling the Beeper Desktop API

1. Open Beeper Desktop.
2. Go to Settings → Developers and toggle Beeper Desktop API on. The server starts on http://127.0.0.1:23373.
3. Still in Developers, open Approved connections, click + to create a new access token, and copy the token — it will not be shown again.

Configuring the token

1. Open Flow Launcher's settings (Ctrl+I) → Plugins → Beeper.
2. Paste the access token into Access Token.
3. Optionally adjust:
   • API URL (default http://127.0.0.1:23373) — only change if you customised the Beeper API host/port.
   • Cache TTL (seconds) (default 30) — how long the chat list is cached locally between queries.
   • Max results (default 30) — maximum number of chats shown per query.

Searching and opening chats

Trigger Flow Launcher and type the action keyword followed by an optional query:

beeper
beeper mom
beeper whatsapp dinner

• An empty query lists your most recent chats (up to the 200 most recent, filtered to Max results).
• A query does a literal token match (case-insensitive, AND across whitespace-separated tokens) over each chat's title, network name, and participant names.
• Each result shows the chat title, network (WhatsApp, iMessage, Telegram, Signal, Discord, etc.), and time since last activity, with the chat's avatar when Beeper exposes a local image path.
• Press Enter on a result to focus Beeper Desktop and navigate to that chat.

API

The plugin is a thin wrapper over the official Beeper Desktop local HTTP API. The endpoints used are:

Method	Path	Purpose
GET	/v1/info	Server discovery (used for diagnostics).
GET	/v1/chats/search?limit=200	Fetch the recent chat list (cached locally).
POST	/v1/focus	Focus Beeper Desktop and navigate to a chatID.

All authenticated requests carry the bearer token as Authorization: Bearer <token>. The full OpenAPI specification is served live by Beeper Desktop at http://127.0.0.1:23373/v1/spec and is documented at developers.beeper.com/desktop-api.

Maintainers

@turingexmachina

Contributing

Issues and pull requests are welcome on the GitHub repository.

Before opening a PR:

• Keep changes focused; describe the user-facing behaviour change in the PR body.
• Match the existing code style (PEP 8 with the conventions already present in main.py).
• If the change affects user-visible behaviour, update the Usage section above.

This project follows the Standard Readme specification — please keep edits to README.md compliant.

License

MIT © turingexmachina