Beeper chat capture

The Beeper integration forwards chat messages from Beeper into Sharick — both sent and received, with the direction preserved. Sharick does not connect to your chat accounts; a forwarder running on your own machine pushes data in with a token you control.

Beeper is third-party software; you choose whether to trust it. If it is ever compromised, revoke its token in Sharick.

Set up with Sharick Desktop (recommended)

Open Settings → Integrations → Beeper in Sharick Desktop. It mints the token, installs the Beeper CLI forwarder as a LaunchAgent (com.sharick.beeper-forwarder), and keeps it repaired and up to date.

Each token carries a rate limit (120 messages/minute by default). Revoke stops a token; you can also delete its saved chat data — during revocation or any time after.

Advanced: set up another computer over SSH

In Sharick Desktop, open Settings → Integrations → Beeper → Advanced: Beeper on another computer. This option supports a Linux computer with Beeper Desktop already running and signed in, Beeper CLI, Python 3, and a systemd user session.

1. Establish a trusted SSH key connection from this computer first. An alias from your SSH config (including a proxy command) or user@hostname works. Sharick does not accept unknown host keys or prompt for SSH passwords.
2. Enter that host and choose Check connection.
3. Choose Set up remote forwarding. Sharick creates the token for you and shows the agreement only when needed. If the old beeper-sharick service is found, explicitly select its replacement option.
4. Check the connected networks and the separate message and participant sync timestamps. A running service alone does not confirm delivery.

Setup uses the remote Desktop API on loopback port 23373, through a dedicated CLI target. A headless Beeper Server profile can have different accounts; it is not selected implicitly. The token is sent through SSH input and stored in a private remote configuration file, not command arguments.

The user service sharick-beeper-desktop.service polls text messages and syncs new or changed chat participant lists. Those lists enable Add to People / Link existing for recipients of sent messages. Incomplete group lists are reported without replacing previously synced participants. Media uploads are not included in this remote setup. Messages longer than 8,192 UTF-8 bytes are imported as a prefix with explicit truncation metadata.

The first run verifies a recent window and catches up the last 24 hours in the background. Failed or incomplete message batches retain their watermark for retry. If a previously captured message is edited in Beeper, the original capture is kept and forwarding continues. Replacing a token creates a separate import identity and can duplicate messages already captured with an older token. Backups of the managed files are kept under ~/.local/share/sharick/beeper-remote/; failed installation attempts restore the previous service where possible.

Keep Beeper Desktop and the Linux user session running. To pause forwarding on that computer, use systemctl --user stop sharick-beeper-desktop.service. To disable it across logins, use systemctl --user disable --now sharick-beeper-desktop.service. Revoke the token in Sharick if the host should no longer be allowed to send chats.

Manual forwarding with the Beeper CLI

If you prefer to run the forwarder yourself, create a token in Settings → Integrations → Beeper and copy the token, webhook URL, and webhook secret immediately — they are shown only once.

Install the CLI:

brew install beeper/tap/cli

Then start forwarding with the webhook URL and secret shown when you created the token (the /beeper/webhook endpoint accepts the CLI’s payloads and X-Beeper-Signature header):

beeper watch --include-type message.upserted \
  --webhook 'https://app.sharick.ai/api/v1/beeper/webhook?key=YOUR_KEY' \
  --webhook-secret 'YOUR_WEBHOOK_SECRET'

Sign-related details: the CLI signs the raw request body with the webhook secret (sha256=<hex HMAC-SHA256>). Event types other than message.upserted are acknowledged and ignored, entries without text are skipped, and messages are deduplicated per chat. Delivery is best-effort: if the forwarder does not retry, gaps are possible. Replays are safe.

beeper watch runs in the foreground and only forwards while it is running. To keep it running across restarts, wrap the command in your own supervisor — on macOS a LaunchAgent works well:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>com.example.chat-forwarder</string>
  <key>ProgramArguments</key>
  <array>
    <string>/opt/homebrew/bin/beeper</string>
    <string>watch</string>
    <string>--include-type</string><string>message.upserted</string>
    <string>--webhook</string>
    <string>https://app.sharick.ai/api/v1/beeper/webhook?key=YOUR_KEY</string>
    <string>--webhook-secret</string><string>YOUR_WEBHOOK_SECRET</string>
  </array>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
</dict>
</plist>

Save it as ~/Library/LaunchAgents/com.example.chat-forwarder.plist and run launchctl load on it. Delivery is fire-and-forget while the watcher is up; messages sent while it is down are not forwarded retroactively.

Troubleshooting

Beeper Desktop has to be running. The CLI reads your chats through the Beeper Desktop app; while Desktop is closed, nothing is forwarded. Forwarding resumes on its own once you open it again.

Check the agent. On macOS, ask launchd what your forwarder is doing:

launchctl print gui/$(id -u)/com.sharick.beeper-forwarder

active count = 1 means it is running. active count = 0 with runs climbing every few seconds means it is crash-looping: launchd keeps restarting a process that dies immediately.

The CLI’s first run is the usual culprit. The Beeper CLI is a single-file binary that unpacks itself into ~/.cache/beeper-cli the first time it runs. Two first runs at the same time — a supervisor starting beeper watch while another command also touches the CLI — leave half-written files there, and every later invocation fails on the corrupt cache. Run beeper --version once by itself before starting any supervisor. If beeper --version already fails:

launchctl bootout gui/$(id -u)/com.sharick.beeper-forwarder
rm -rf ~/.cache/beeper-cli
beeper --version
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.sharick.beeper-forwarder.plist

Sharick Desktop can do this for you. Settings → Integrations → Beeper says which of four things is true:

• running — forwarding is live on this Mac.
• not running — with a Repair button that runs exactly the sequence above. You get this whenever the agent is down and the CLI itself is failing, even while Beeper Desktop is closed: a CLI that will not start is not something opening Desktop can fix.
• waiting for Beeper Desktop — the agent is fine and Desktop is closed. Forwarding resumes on its own when you open it; there is nothing to repair.
• older layout — with an Update button, described next.

Repair reuses the webhook token already installed on the machine, so you never have to create a new one — the webhook secret is shown only once — and it also rewrites the LaunchAgent in the current layout on its way through.

After a Sharick Desktop update. A new version can change how the LaunchAgent is generated, and launchd keeps running the old one until something rewrites it — which is why an up-to-date app can still be forwarding through an old agent. Settings then shows the older-layout line, with an Update button once the agent is running or Beeper Desktop is reachable. It rewrites the agent in the current layout, reusing the token already on the machine, so you never need a new one. A stopped forwarder needs no separate Update: Repair does the same rewrite.

Logs. The forwarder writes its errors to ~/Library/Logs/Sharick/beeper-forwarder.log.

Privacy and deletion

Captured messages are kept until you delete them. During revocation or after a token is revoked, you can wipe its saved chat data without removing the token record; deleting your Sharick account removes it all as well. Remember that chat history includes other people — forward only what you are comfortable storing.