How to use the Beeper Chat History Search agent skill

What is an agent skill and what does the beeper skill do?

An agent skill is a folder of instructions, packaged with a file called SKILL.md, that an AI agent can load when a task matches the skill's description. The skill tells the agent how to approach a specific job, which saves you from explaining the method every time.

The beeper skill covers local Beeper history questions, especially vague contact hints across iMessage and WhatsApp bridges. The agent first inspects accounts and rooms, then uses full-text search (FTS) over messages, narrows results by date, participant and room, and reports the room and account names, the date span, and a confidence level. It is meant for reading your own history, not sending messages.

What you need before installing

The skill is designed for macOS with the Beeper app installed and its local database present. It reads a file at ~/Library/Application Support/BeeperTexts/index.db, so the agent needs read access to that file. It also uses the sqlite3 command-line tool.

If you use Windows or Linux, or you do not have the Beeper app on a Mac, this skill will not point at a database that exists on your machine.

• macOS with the Beeper app installed and its local database present
• The sqlite3 command-line tool
• Read access to ~/Library/Application Support/BeeperTexts/index.db

How do you install the beeper skill?

Download the ZIP for the beeper skill from this page and unzip it. You have two options depending on how you use your agent.

For Claude Code, place the unzipped skill folder in ~/.claude/skills/ to make it available everywhere, or in a project's .claude/skills/ folder to limit it to that project.

In the Claude apps, you can upload the skill instead. Open Settings, go to Capabilities, then Skills, and upload it there.

• Claude Code, all projects: ~/.claude/skills/
• Claude Code, one project: the project's .claude/skills/ folder
• Claude apps: Settings → Capabilities → Skills, then upload

How do you trigger the skill with a natural request?

You do not need a special command. Describe what you are trying to find, and mention the vague details you remember. The skill's description covers contact hints and WhatsApp or iMessage traces, so requests about old conversations with a person or across those bridges are the ones it is built for.

Give whatever detail you have, even if it is partial. The agent will list accounts and rooms first, so a rough name or a topic is enough to start.

• Find the WhatsApp chat where someone mentioned a dentist appointment last spring.
• Which iMessage thread did I discuss the apartment lease in, and roughly when?
• Search my Beeper history for messages about the car repair quote.

What does the agent actually do with the database?

The skill tells the agent to start by inspecting accounts and rooms before broad searching. A typical probe lists accounts from the accounts table:

• Identify likely account, bridge and room from the accounts, participants and room tables
• Use FTS on the mx_room_messages_fts table for text discovery
• Narrow by date, participant and room
• Report room and account names, date spans and confidence

Safety: scripts, network and private data

The skill runs scripts, because it calls sqlite3 against your local database. It does not use the network. The database can contain private messages, so the skill's instructions say to keep results local.

Be careful about pasting search results into shared documents, chats or online tools. Review what the agent reports before you share any of it beyond your own machine.

• Runs scripts: yes (sqlite3 queries on your local database)
• Uses network: no
• Keep results on your machine, since the database holds private messages

Tips for better results

Start with a specific word or a name, and add a rough date range if you have one. The agent reads confidence levels into its answer, so ask it to explain why it chose a room if you want to check its reasoning.

If the first search returns too much, ask the agent to narrow by participant or date. If it returns nothing, try a different spelling or a shorter keyword, since full-text search matches words rather than exact phrases you may misremember.

• Give a rough date range to narrow results
• Name a participant if you know who was in the chat
• Ask for the confidence level and the reasoning behind it
• Try alternate spellings or shorter keywords when nothing matches