From a88a05e8a480b3982cecf26f69010119a0ec0543 Mon Sep 17 00:00:00 2001 From: Jules LIBERT Date: Wed, 28 Jan 2026 10:28:22 +0100 Subject: [PATCH] feat: add Agent Skills for AI coding assistants Add SKILL.md following the Agent Skills open standard, enabling installation via `npx skills add blqke/beepctl` for 25+ AI agents (Claude Code, Cursor, VS Code, GitHub Copilot, etc.) --- README.md | 24 ++++++ skills/beepctl/SKILL.md | 171 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 195 insertions(+) create mode 100644 skills/beepctl/SKILL.md diff --git a/README.md b/README.md index 1c3b254..f2539bf 100644 --- a/README.md +++ b/README.md @@ -284,6 +284,30 @@ src/ - **Bun** for standalone binary compilation - **@beeper/desktop-api** SDK +## AI Agent Integration + +beepctl includes an [Agent Skill](https://agentskills.io) for AI coding assistants. + +**Supported agents:** Claude Code, Cursor, VS Code, GitHub Copilot, OpenAI Codex, Gemini CLI, Goose, Amp, and [25+ more](https://agentskills.io). + +### Install via npx skills + +```bash +npx skills add blqke/beepctl +``` + +### Manual install (Claude Code) + +```bash +cp -r skills/beepctl ~/.claude/skills/ +``` + +### Manual install (Cursor) + +```bash +cp -r skills/beepctl ~/.cursor/skills/ +``` + ## Acknowledgments Inspired by [beeper-cli](https://github.com/krausefx/beeper-cli) by [@krausefx](https://github.com/krausefx). diff --git a/skills/beepctl/SKILL.md b/skills/beepctl/SKILL.md new file mode 100644 index 0000000..18759c2 --- /dev/null +++ b/skills/beepctl/SKILL.md @@ -0,0 +1,171 @@ +--- +name: beepctl +description: Use when sending messages, searching chats, or managing conversations across messaging platforms (Telegram, WhatsApp, Slack, iMessage, etc.) via Beeper Desktop API. +metadata: + author: blqke + homepage: https://github.com/blqke/beepctl + clawdbot: + emoji: "🐝" + requires: + bins: ["beepctl"] + install: + - id: npm + kind: npm + package: beepctl + global: true + bins: ["beepctl"] + label: "Install beepctl (npm)" +--- + +# beepctl + +CLI for [Beeper Desktop API](https://developers.beeper.com/desktop-api) — unified messaging from your terminal. Control all your messaging platforms (Telegram, WhatsApp, Slack, iMessage, etc.) through one interface. + +📖 **Setup & installation:** see [GitHub repo](https://github.com/blqke/beepctl) + +## Quick Start + +```bash +beepctl accounts # List connected accounts +beepctl chats list # List recent chats +beepctl chats list --search "John" # Find a chat +beepctl search "meeting" --after "1d ago" # Search messages +beepctl send "Hello!" # Send a message +``` + +## Commands + +### Auth Management +```bash +beepctl auth show # Check auth status and token +beepctl auth set # Set API token +beepctl auth clear # Clear saved token +``` + +### Accounts +```bash +beepctl accounts # List all connected accounts +``` + +### Browse Chats +```bash +beepctl chats list # List inbox (non-archived) +beepctl chats list --limit 20 # Limit results +beepctl chats list --search "John" # Filter by name +beepctl chats list --inbox archive # Archived chats only +beepctl chats list --inbox low-priority # Low-priority chats +beepctl chats list --inbox all # All chats +beepctl chats list --type group # Filter by type (single/group/any) +beepctl chats list --unread-only # Unread chats only +beepctl chats list --activity-after "1d ago" # Recent activity filter +beepctl chats show # Detailed chat info with participants +beepctl chats create # Create new chat +``` + +**Inbox filters:** `primary` (default), `archive`, `low-priority`, `all` + +### List Messages +```bash +beepctl messages # Recent messages from a chat +beepctl messages --limit 10 # Limit results +beepctl messages work --after "1d ago" # Use alias + time filter +beepctl messages --before "1h ago" # Messages before a time +``` + +### Search Messages +```bash +beepctl search "query" # Search across all chats +beepctl search "query" --limit 10 # Limit results +beepctl search "meeting" --after "1d ago" # Time filter +beepctl search "hello" --chat work # Filter by chat/alias +beepctl search "files" --media file # Filter by media type +beepctl search "dm" --chat-type single # Filter by chat type +beepctl search "update" --sender others # Filter by sender (me/others) +beepctl search "msg" --account # Filter by account +beepctl search "todo" --include-low-priority # Include low-priority chats +beepctl search "important" --exclude-muted # Exclude muted chats +``` + +**Combine filters:** +```bash +beepctl search "deploy" --chat work --sender others --after "1d ago" --media link +beepctl search "hello" --chat work family # Multiple chats (space-separated) +beepctl search "test" --chat id1,id2,id3 # Multiple chats (comma-separated) +``` + +**Time formats:** `1h ago`, `2d ago`, `3w ago`, `1mo ago`, `yesterday`, `today` +**Media types:** `any`, `video`, `image`, `link`, `file` + +### Aliases +Create shortcuts for frequently used chat IDs: + +```bash +beepctl alias list # List all aliases +beepctl alias add work # Create alias +beepctl alias show work # Show alias value +beepctl alias remove work # Remove alias +beepctl send work "Using alias!" # Use alias in any command +``` + +### Archive Chats +```bash +beepctl archive # Archive a chat +beepctl archive --unarchive # Unarchive +beepctl archive work # Use alias +beepctl archive --quiet # No confirmation message +``` + +### Send Messages + +⚠️ **NEVER send messages without explicit user approval first!** +Always show the message content and recipient, then ask for confirmation. + +```bash +beepctl send "Hello!" # Send message +beepctl send myself "Quick note" # Send to self +beepctl send "Reply" --reply-to # Reply to message +beepctl send "msg" --quiet # No confirmation output +``` + +### Focus (Bring to Foreground) +```bash +beepctl focus # Bring Beeper to foreground +beepctl focus # Open a specific chat +beepctl focus -m # Jump to specific message +beepctl focus -d "draft" # Pre-fill draft text +beepctl focus -a /path/file # Pre-fill draft attachment +``` + +### Send Media +`beepctl send` only supports text. To send media, use focus with draft: + +```bash +beepctl focus -a /path/to/image.png -d "Caption" +# Then press Enter in Beeper to send +``` + +### Contacts +```bash +beepctl contacts search # Search contacts on an account +``` + +### Download Attachments +```bash +beepctl download # Download attachment (mxc:// URLs) +beepctl download -o /path # Save to specific path +``` + +### Reminders +```bash +beepctl reminders set 30m # Remind in 30 minutes +beepctl reminders set 1h # Remind in 1 hour +beepctl reminders set 2d # Remind in 2 days +beepctl reminders set tomorrow # Remind tomorrow +beepctl reminders clear # Clear reminder +``` + +## Tips + +- Chat IDs look like: `!gZ42vWzDxl8V0sZXWBgO:beeper.local` +- Use aliases to avoid typing long chat IDs +- The special alias `myself` sends to your own chat