twitter-lite/docs/beeper-integration-research.md

Beeper integration research

Researched 2026-09-28. Proposal only; no integration was installed during research.

Current direction

External Codex performs inference, reads Beeper, and reads/writes life under Rensheng conventions. life is the CRM source of truth, serving the role Scrapbox plays in Beeper Copilot. This application accepts structured publications and provides the UI, persistent execution state, and user feedback. It does not need a new CRM inference runtime or life filesystem editing engine.

Home combines routines, optional tasks, measurements and communication as activities, with different controls for each kind. A weight entry, reply editor, routine checklist and simple completion control belong in one daily overview.

See external agent publishing for the concrete contract and gbrain cron findings, and the Beeper Copilot screenshot gallery for UI references. This supersedes earlier proposals for app-managed inference and direct app-to-life editing.

Verified locally

• Beeper CLI 0.6.2 and Server run on UM790-Pro.
• Public GET http://127.0.0.1:23373/v1/info returned Beeper 4.3.149 on Linux, running, remote access disabled and MCP enabled.
• Discovery exposes /v0/mcp, /v1/ws, and /v1/spec. The live OpenAPI reports API version 5.0.0, distinct from the application/SDK version domains.
• The existing CLI target um790 successfully retrieved server info using --read-only. This is discovery verification, not proof of complete account synchronization or successful message delivery.
• No private conversation bodies were fetched, and no Beeper configuration or messages were changed. The screenshots contain public LP demonstrations.

The official CLI supports headless Server as well as Desktop. No additional GUI machine or remote tunnel is needed here.

HTTP, WebSocket, MCP and CLI

Interface	Role
Beeper HTTP / CLI / SDK	Read messages, reconcile changes, perform approved sends
Beeper WebSocket	Live UI changes or a coalesced signal for the external worker
App write API, optionally wrapped as CLI/MCP	Receive Codex results without inference
App context/request API	Expose user decisions, pending requests and revisions
Browser HTTP + SSE	Persisted views, direct UI operations and update notifications

Existing CLI authentication can be reused with bounded, fixed-argument api get calls and watch --target um790 --read-only --json. Do not expose arbitrary CLI/RPC command strings as agent tools. The official TypeScript SDK is an alternative after explicitly provisioning an application credential. Choose one transport inside the adapter; automatic CLI/SDK fallback is unnecessary.

The MCP guide uses Streamable HTTP. The changelog removes the old Beeper MCP SSE transport; our own browser SSE can remain.

Synchronization findings

The running server's /v1/spec explicitly states that WebSocket delivery is at-most-once, has no replay after reconnect, and uses per-connection sequence numbers. The WebSocket guide also describes experimental status and best-effort payloads. HTTP reconciliation is required after disconnects and periodically. Do not start Codex per message.

Subscribe before initial reconciliation, track changed chats during it, then refetch those chats. Commit progress only after persistence. Use canonical target/account/chat/message IDs and revisions or content hashes. Edited/deleted evidence invalidates affected drafts. One missing list result does not prove deletion. CLI watch webhooks are best-effort and can drop on queue overflow; a same-machine worker avoids needing a webhook receiver, not the need to reconcile.

The message API returns opaque cursors. life's backfill guide records missed/duplicated pages when CLI message IDs were used as cursors, plus API order differing from timestamp order. Do not stop pagination merely because a date boundary was crossed.

Reference findings

life

life/briefs/2026-09-25-executive-support-design.md describes source-backed reply assistance, explicit review and durable personal context. Existing life/docs/beeper-backfill.md and life/scripts/beeper_backfill.py implement reviewed, resumable CLI backfill on this machine.

That helper is not a continuous inbox worker: discovery covers 100 recent chats, pages require review/acknowledgment, and some quotes, forwarded messages and attachments are deliberately excluded. Its output is not a complete conversation view. Reuse its identity/provenance rules. Its guide warns that CLI 0.6.2 raw status --json can expose credentials.

Codex should maintain existing life domain pages. The app displays published CRM projections; user corrections return as durable requests to Codex. It must distinguish pending corrections from confirmed life changes.

gbrain

Inspected revision e78f1c38b947b053f3a46881340f74f316be855a. No Beeper-specific connector was found. Its open-loop design informs requests, commitments, waiting and source freshness. Its sync implementation advances progress after successful ingestion. Apply those principles in the external Codex workflow. The publishing proposal covers its host scheduler, job execution and transactional write patterns.

Rensheng / OpenBrief

Inspected local revision c06c4e3f290800752a0c252c84fbca0eed61e45d. Rensheng's setup reuses existing source tools. OpenBrief's proposal-only MCP and snapshot transport design are useful boundaries. Neither requires adopting its Rust application or duplicating its filesystem workflow in this app.

Beeper Copilot

The LP was inspected in Chromium at desktop/mobile sizes. The three-pane view, person context, evidence chips and reply review are concrete UI references, documented in the capture gallery. Its linked source repository returned 404 to unauthenticated access; screenshots verify the LP presentation, not backend behavior. Use life in the Scrapbox role. EventKit, macOS deployment and the demo's relationship scoring are not requirements here.

Sending

The send API returns a pending ID, not delivery confirmation. Bind approval to exact draft revision, recipient and reply target, then resolve pending IDs before marking sent. The inspected schema does not document a client idempotency key, so local deduplication cannot guarantee exactly-once delivery after an ambiguous failure.

Disable automatic send retries and reconcile uncertain results. The SDK defaults include retries on transport errors and timeouts. Publishing a draft/activity must not send a message.

The current execution support is still fictional and in-memory. Establish the external agent's write interface and persistent typed activities before installing scheduled automation.