Beeper Desktop API Knowledge Skill

Beeper Desktop API Knowledge

This skill provides knowledge about the Beeper Desktop API and the beeper-ai integration.

Beeper Desktop API Overview

Beeper Desktop provides a local REST API for accessing messages across all connected platforms.

Base URL

http://localhost:23373

Authentication

Requires an access token set in the BEEPER_ACCESS_TOKEN environment variable. Get the token from: Beeper Desktop > Settings > Developers

Key Endpoints

Status

GET /api/v1/status

Check if the API is running.

Accounts

GET /api/v1/accounts

List all connected messaging accounts (bridges).

Chats

GET /api/v1/accounts/{account_id}/chats
GET /api/v1/chats/{chat_id}

List chats for an account or get a specific chat.

Messages

GET /api/v1/chats/{chat_id}/messages
POST /api/v1/chats/{chat_id}/messages

Get or send messages.

Fabric Integration

beeper-ai uses Fabric for AI features instead of direct Anthropic API calls.

Fabric Server

http://localhost:8080

Start with: fabric --serve --address :8080

Key Patterns Used

| Pattern | Use Case | |---------|----------| | summarize | Conversation summaries | | analyze_personality | Style guide generation | | write_essay | Reply generation | | extract_wisdom | Key insights extraction | | improve_writing | Reply refinement |

Fabric API

POST /chat
{
  "prompts": [{
    "userInput": "...",
    "patternName": "summarize",
    "model": "claude-sonnet-4-20250514"
  }]
}

beeper-ai Package Structure

src/beeper_ai/
├── core/
│   ├── config.py          # Settings (pydantic-settings)
│   └── exceptions.py      # Custom exceptions
├── api/
│   ├── client.py          # BeeperClient wrapper
│   └── models.py          # Data models (Account, Chat, Message)
├── fabric/
│   ├── client.py          # FabricClient for AI calls
│   ├── patterns.py        # Pattern definitions
│   └── sessions.py        # Session management
├── ai/
│   ├── assistant.py       # Main ChatAssistant facade
│   ├── style_analyzer.py  # StyleGuide generation
│   ├── summarizer.py      # Conversation summarization
│   └── smart_reply.py     # Reply generation
├── search/
│   ├── engine.py          # SearchEngine
│   └── filters.py         # SearchFilters
└── cli/
    └── main.py            # Click CLI commands

Configuration

Environment variables (set in .env):

BEEPER_ACCESS_TOKEN=xxx
BEEPER_BASE_URL=http://localhost:23373
FABRIC_BASE_URL=http://localhost:8080
FABRIC_DEFAULT_MODEL=claude-sonnet-4-20250514
STYLE_GUIDE_PATH=./data/style_guide.json
MIN_MESSAGES_FOR_ANALYSIS=100

CLI Commands

beeper-ai status                    # Check connectivity
beeper-ai search "query"            # Search messages
beeper-ai summarize <chat_id>       # Summarize conversation
beeper-ai reply <chat_id>           # Generate reply
beeper-ai analyze-style             # Create style guide

Common Tasks

Find a Chat ID

Search for messages from the person/conversation
The chat_id appears in search results

Generate a Style-Matched Reply

Ensure style guide exists (analyze-style if needed)
Run reply <chat_id> - style is applied automatically

Troubleshooting

"Connection refused" on Beeper: Ensure Desktop app is running
"Connection refused" on Fabric: Start with fabric --serve
"Insufficient data": Need more messages for style analysis

Agent Skills: Beeper Desktop API Knowledge

Install this agent skill to your local

Skill Files