OpenParable
Skip to content
← Back to skills

Roadrunner

Apps & Automation
roadrunner

Roadrunner is an Agent Skill for apps & automation published in the sundial-org/awesome-openclaw-skills repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Beeper Desktop CLI for chats, messages, search, and reminders.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/sundial-org/awesome-openclaw-skills/blob/HEAD/skills/roadrunner/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/roadrunner, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

roadrunner (rr)

Use rr when the user explicitly wants to operate Beeper Desktop via the local API (send, search, list chats/messages, reminders, focus). Prefer --agent for agent use (forces JSON, envelope, no-input, readonly).

Safety

  • Require explicit recipient (chat ID) and message text before sending.
  • Confirm or ask a clarifying question if the chat ID is ambiguous.
  • Use --agent for safe agent defaults: rr --agent --enable-commands=chats,messages,status chats list
  • Use --readonly to block writes: rr --readonly chats list --json
  • Use --enable-commands to allowlist: rr --enable-commands=chats,messages chats list --json
  • Use --envelope for structured errors: rr --json --envelope chats get "!chatid"

Setup (once)

  • rr auth set <token>
  • rr auth status --check
  • rr doctor

Common commands

  • List accounts: rr accounts list --json
  • Capabilities: rr capabilities --json
  • Search contacts: rr contacts search "<account-id>" "Alice" --json
  • Search contacts (flag): rr contacts search "Alice" --account-id="<account-id>" --json
  • Resolve contact: rr contacts resolve "<account-id>" "Alice" --json
  • Resolve contact (flag): rr contacts resolve "Alice" --account-id="<account-id>" --json
  • List chats: rr chats list --json
  • Search chats: rr chats search "John" --json
  • Search chats (filters): rr chats search --inbox=primary --unread-only --json
  • Search chats (activity): rr chats search --last-activity-after="2024-07-01T00:00:00Z" --json
  • Search by participant name: rr chats search "Jamie" --scope=participants --json
  • Resolve chat: rr chats resolve "Jamie" --json
  • Get chat: rr chats get "!chatid:beeper.com" --json
  • Create chat (single): rr chats create "<account-id>" --participant "<user-id>"
  • Create chat (group): rr chats create "<account-id>" --participant "<user-a>" --participant "<user-b>" --type group --title "Project Chat" --message "Welcome!"
  • Default account for commands: rr --account="imessage:+123" chats list --json
  • Account aliases: rr accounts alias set work "slack:T123"
  • List messages: rr messages list "!chatid:beeper.com" --json
  • List messages (download media): rr messages list "!chatid:beeper.com" --download-media --download-dir ./media --json
  • Search messages: rr messages search "dinner" --json
  • Search messages (filters): rr messages search --sender=me --date-after="2024-07-01T00:00:00Z" --media-types=image --json
  • Send message: rr messages send "!chatid:beeper.com" "Hello!"
  • Reply to message: rr messages send "!chatid:beeper.com" "Thanks!" --reply-to "<message-id>"
  • Send message from file: rr messages send "!chatid:beeper.com" --text-file ./message.txt
  • Send message from stdin: cat message.txt | rr messages send "!chatid:beeper.com" --stdin
  • Tail messages (polling): rr messages tail "!chatid:beeper.com" --interval 2s --stop-after 30s --json
  • Wait for message: rr messages wait --chat-id="!chatid:beeper.com" --contains "deploy" --wait-timeout 2m --json
  • Message context: rr messages context "!chatid:beeper.com" "<sortKey>" --before 5 --after 2 --json
  • Draft message (pre-fill without sending): rr focus --chat-id="!chatid:beeper.com" --draft-text="Hello!"
  • Draft message from file: rr focus --chat-id="!chatid:beeper.com" --draft-text-file ./draft.txt
  • Draft with attachment: rr focus --chat-id="!chatid:beeper.com" --draft-attachment="/path/to/file.jpg"
  • Download attachment: rr assets download "mxc://example.org/abc123" --dest "./attachment.jpg"
  • Reminders: rr reminders set "!chatid:beeper.com" "2h" / rr reminders clear "!chatid:beeper.com"
  • Archive chat: rr chats archive "!chatid:beeper.com" / rr chats archive "!chatid:beeper.com" --unarchive
  • Focus app: rr focus
  • Global search: rr search "dinner" --json
  • Status summary: rr status --json
  • Status by account: rr status --by-account --json
  • Unread rollup: rr unread --json
  • Global search includes in_groups for participant matches.

Pagination

  • Chats: rr chats list --cursor="<oldestCursor>" --direction=before --json
  • Messages list: rr messages list "!chatid:beeper.com" --cursor="<sortKey>" --direction=before --json
  • Messages search (max 20): rr messages search "project" --limit=20 --json
  • Messages search page: rr messages search "project" --cursor="<cursor>" --direction=before --json
  • Global search message paging (max 20): rr search "dinner" --messages-limit=20 --json
  • Global search message page: rr search "dinner" --messages-cursor="<cursor>" --messages-direction=before --json

Notes

  • Requires Beeper Desktop running; token from app settings.
  • Token stored at ~/.config/beeper/config.json. BEEPER_TOKEN overrides.
  • BEEPER_ACCOUNT sets the default account ID (aliases supported).
  • Message search is literal word match (not semantic).
  • rr contacts resolve is strict and fails on ambiguous names; resolve by ID after contacts search when needed.
  • If a DM title shows your own Matrix ID, use --scope=participants to find by name.
  • JSON output includes display_name for single chats (derived from participants).
  • Message JSON includes is_sender, is_unread, attachments, and reactions.
  • downloaded_attachments is only populated when --download-media is used.
  • rr messages send returns pending_message_id (temporary ID).
  • Prefer --json (and --no-input) for automation.
  • BEEPER_URL overrides API base URL; BEEPER_TIMEOUT sets timeout in seconds.
  • JSON/Plain output goes to stdout; errors/hints go to stderr.
  • Destructive commands prompt unless --force; --no-input/BEEPER_NO_INPUT fails without --force.
  • Use --fail-if-empty on list/search commands to exit with code 1 if no results.
  • Use --fields with --plain to select columns (comma-separated).
  • In bash/zsh, ! triggers history expansion. Prefer single quotes, or disable history expansion (set +H in bash, setopt NO_HIST_EXPAND in zsh).
  • rr version --json returns features array for capability discovery.
  • rr capabilities --json returns full CLI capability metadata.
  • Envelope error codes: AUTH_ERROR, NOT_FOUND, VALIDATION_ERROR, CONNECTION_ERROR, INTERNAL_ERROR.