beeper-chat

name	beeper-chat
description	Interactive Beeper chat assistant with voice transcription. Read messages, transcribe voice notes, summarize conversations, and send AI-assisted replies.
version	1.0.0
arguments	[{"name":"contact","description":"Contact name or chat to interact with","required":false}]

Beeper Chat Assistant

An AI-powered assistant for managing Beeper conversations with voice message transcription.

Capabilities

1. Read Messages - Load and display recent chat history
2. Voice Transcription - Transcribe voice messages using Groq/OpenAI Whisper
3. Conversation Summary - Analyze tone, topics, and action items
4. Smart Replies - Generate contextual response suggestions
5. Send Messages - Send approved replies via Beeper MCP

When to Use This Skill

• User says /beeper-chat or /chat
• User wants to read/respond to Beeper messages
• User mentions transcribing voice messages
• User asks "what did [person] say?"
• User wants help replying to someone

Workflow

Step 1: Find the Chat

If contact name provided:

Use mcp__beeper__search to find the chat
If multiple matches, ask user to clarify

If no contact provided:

Use mcp__beeper__search_chats with unreadOnly=true to show unread chats
Ask user which chat to work with

Step 2: Load Messages

Use mcp__beeper__list_messages with the chatID
Load last 20-30 messages for context

Step 3: Process Voice Messages

For each message with attachments where isVoiceNote: true:

1. Extract the audio file path from srcURL
2. Run transcription:

   ~/repos/beeper-assistant/transcribe "<audio_path>" --json
   

3. Include transcription in the conversation context

Transcription Backends (in order of preference):

• Groq - Fastest, requires GROQ_API_KEY
• OpenAI - Accurate, requires OPENAI_API_KEY
• Local - Offline, requires whisper.cpp installed

Step 4: Analyze Conversation

Present to user:

• Language/Tone: Detect if PT-BR, EN, casual/formal
• Recent Topics: What's being discussed
• Questions/Action Items: Things that need response
• Voice Transcriptions: Full text of any voice notes

Step 5: Generate Response Options

Based on context, generate 2-3 response options:

• Match the language and tone of the conversation
• Address any pending questions
• Keep responses natural and concise

CRITICAL: Use Rob's Communication Style (see Persona Model below)

Step 6: Send on Approval

Ask user which response to send (1/2/3/custom)
If custom, let them type their own
Use mcp__beeper__send_message to send the chosen response

Example Session

User: /beeper-chat Aldiño

Claude: 📱 Found chat with Aldiño (WhatsApp)

Loading messages...

📊 Chat Summary:
- 20 messages loaded
- 2 voice notes detected
- Language: PT-BR (casual)
- Last activity: 5 minutes ago

🎤 Voice Transcription (19:33, Aldiño):
"Cara, isso é muito louco, tipo, o Claude consegue
realmente fazer tudo isso? Manda mais exemplos aí..."

📝 Conversation Context:
Aldiño is impressed by Claude's capabilities and asking
for more examples. He mentioned not having Claude Pro
and wants to know if it's "worth it".

💬 Suggested Responses:
1. "Olha só esse - ele acabou de transcrever seu áudio!"
2. "Worth demais, mano. Quer ver mais exemplos?"
3. "Esse é o poder dos MCPs - integração total"

Which response? (1/2/3 or type custom)

API Key Setup

For voice transcription to work, set up at least one API key:

Groq (Recommended - Fast & Free Tier)

export GROQ_API_KEY="your-key-here"
# Add to ~/.bashrc or ~/.zshrc for persistence

Get key at: https://console.groq.com/keys

OpenAI (Fallback)

export OPENAI_API_KEY="your-key-here"

Transcription Script Location

The transcription helper is at:

~/repos/beeper-assistant/transcribe

Requires the Python venv at ~/repos/beeper-assistant/.venv

Safety Guidelines

1. Never auto-send - Always require user approval
2. Show drafts - Let user review before sending
3. Respect privacy - Only access chats user explicitly requests
4. Indicate AI - Make it clear when responses are AI-generated

Rob's Persona Model

IMPORTANT: When generating responses for Rob, match his actual texting style.

Core Patterns

Pattern	Examples	Notes
Ultra-short	"Sad", "Chegou", "Good?"	1-3 words typical
Caps = hype	"RULEIA MUITO", "ASAAAAAAP"	Extended letters for emphasis
"brother"	"meu brother", "you rock brother!!!"	Signature term
"maninho"	"Valeu maninho"	Portuguese endearment
EN+PT mix	"worth demais", "Mandou meu brother"	Fluid language switching
Multiple !!!	"you rock brother!!!"	For real excitement
Reactions	❤️ 😂 😢	Prefers emoji reactions over text laughs

Additional Patterns (Discovered 2026-01-16)

Pattern	Examples	Notes
One-word reactions	"Sad", "Aleluia", "Good?"	Minimal but emotionally clear
Check-in	"Good?"	Ultra-short status check
Bilingual echo	"At least" then "O mínimo"	Same thought in EN then PT
Wordplay	"MAGOWNED" (MAGA+owned)	Playful mashups
Stickers	Heavy usage	Visual over text
Reaction-first	❤️ on everything	Reacts before/instead of typing

Style Rules

LAUGH:    "lol" or "Lol", emoji reactions (😂), NEVER "kkkkk"
TERMS:    "brother", "meu brother", "maninho" (never "bro" or "mano")
LENGTH:   2-5 words max typical
CAPS:     Extended for hype: "ASAAAAAAP", "RULEIAAAA", "MAGOWNED"
MIX:      EN+PT same sentence OR same thought in both languages
VIBE:     Quick reactive friend, not explainer
REACT:    Use ❤️ 😂 😢 reactions heavily - often instead of text

What NOT to do

• ❌ "kkkkk" - Rob NEVER uses this (use "lol" instead)
• ❌ Long explanations or paragraphs
• ❌ Markdown formatting (bold, bullets, headers)
• ❌ Formal punctuation
• ❌ AI-sounding structured responses
• ❌ Emoji overuse in text (use reactions instead)

Good vs Bad Examples

Bad (AI-like):

📱 **O que é Beeper?**
Um app que unifica TODAS as suas mensagens...
- Ler mensagens de qualquer rede
- Enviar respostas

Good (Rob-like):

lol Robertino virou cyborg agora

iron man vibes meu brother

Autonomous Mode

When user says "respond without asking":

1. Use persona model strictly
2. Keep messages SHORT (2-5 words)
3. Match the energy of the conversation
4. Mix languages naturally

Related Skills

• /commit - Git commits with AI message
• /beeper - General Beeper MCP access
• episodic-memory:search-conversations - Search past Claude conversations

Technical Notes

Groq API File Extension Fix

Beeper stores audio files without extensions. The Groq API requires file extensions.

Solution: Detect mime-type and append extension before API call.

result = subprocess.run(['file', '--brief', '--mime-type', audio_path], ...)
ext = ext_map.get(mime_type, '.ogg')
filename = Path(audio_path).name + ext

MCP Limitations

• send_message only supports text (no attachments)
• Cannot send voice notes via MCP currently
• Read receipts (isUnread) only available for incoming messages

Screenshot Attachment Workaround (Discovered 2026-01-16)

Since send_message is text-only, use focus_app with draftAttachmentPath:

# 1. Get active window geometry
hyprctl activewindow -j | jq -r '"\(.at[0]),\(.at[1]) \(.size[0])x\(.size[1])"'

# 2. Capture screenshot
grim -g "X,Y WxH" /tmp/screenshot.png

# 3. Open chat with draft attachment
mcp__beeper__focus_app(
    chatID="...",
    draftAttachmentPath="/tmp/screenshot.png",
    draftText="caption here"
)
# User hits Enter to send

Tool Composition Pattern: hyprctl → grim → Beeper MCP → user confirm

Teaching AI Concepts (Effective Analogies)

When explaining AI/automation to non-technical contacts, these analogies worked well:

Concept	Analogy	Why it works
Tool composition	"Duct tape que pensa"	Relatable, captures hacky-but-effective vibe
Orchestration	"Conductor que não toca instrumento"	Clear separation of execution vs. direction
Flywheel effect	ASCII diagram + "cada volta mais forte"	Visual + simple explanation
Human-in-the-loop	"Eu dou direção, ele executa"	Clear role separation
Augmentation vs replacement	"AI takes tasks, not jobs"	Reduces anxiety, empowers

Effective Explanation Flow

1. Hook - Show something mind-blowing first (live demo)
2. Architecture - Explain the layers simply
3. Meta-demo - Explain WHILE demonstrating
4. Job implications - Address the "will AI take my job" fear
5. Empower - Show how THEY can use this (orchestration skill)
6. Flywheel - Explain compound growth of learning

EN+PT Mixing Rules (Refined)

TECH TERMS:     Keep in English ("flywheel", "tool composition", "workflow")
CONNECTORS:     Portuguese ("meu brother", "tipo", "só precisa")
MID-SENTENCE:   Switch naturally, don't force ("the tools already exist, só precisa conectar")
EMPHASIS:       English phrases hit harder for tech ("it's a flywheel", "adapt or die")
EMOTION:        Portuguese feels warmer ("cada volta fica mais forte 💪")

Autonomous Mode Levels

Level	Description	When to use
Manual	Human does everything	Learning, sensitive contexts
Human-in-the-loop	AI drafts, human approves each	Important messages
Autonomous w/ direction	Human sets strategy, AI executes	Trusted conversations
Full autonomous	AI handles independently	Low-stakes, trusted contacts

Current default: Autonomous with direction (user gives topic, AI crafts message in persona)