bluesky-poller

name	bluesky-poller
description	Monitor Bluesky notifications (replies, mentions, quotes) on a schedule. Ready-to-use poller following the pollers.json contract with follow-gate trust tiers. Install from ClawHub or copy into your agent's skills/ folder.

Bluesky Notification Poller

Monitors your Bluesky account for new replies, mentions, and quotes. Emits events to the agent only when there's something actionable.

Installation

Install from ClawHub:

npx clawhub install bluesky-poller

Or copy this skill directory into your agent's skills/ folder.

After installation, call reload_pollers to register the poller with the scheduler.

Setup

1. Set environment variables

The poller reads credentials from the agent's environment (.env file or system env):

Variable	Required	Description
BLUESKY_HANDLE	yes	Your Bluesky handle (e.g., agent.bsky.social)
BLUESKY_APP_PASSWORD	yes	App password from Bluesky Settings > App Passwords

Important: Use a dedicated agent account, not a personal account. The poller doesn't mark notifications as read, but using a separate account keeps things clean.

2. Configure pollers.json

The skill ships with a default pollers.json that polls every 5 minutes:

{
  "pollers": [
    {
      "name": "bluesky-mentions",
      "command": "python poller.py",
      "cron": "*/5 * * * *"
    }
  ]
}

Adjust the cron schedule as needed. For lower-traffic accounts, */15 * * * * (every 15 minutes) is fine.

3. Reload pollers

After installation, call reload_pollers to register the poller with the scheduler.

What It Reports

The poller emits events for:

• Replies to your posts
• Mentions of your handle
• Quote posts of your content

Each event includes the author, text, and URIs needed to respond.

Likes and follows are ignored — they don't require agent action.

Trust Tiers (Follow-Gate)

Events from accounts you follow are emitted as normal prompts. Events from accounts you don't follow are prefixed with [PERMISSION NEEDED] — the agent should ask the operator before engaging.

The follow list is cached for 1 hour to avoid API rate limits.

Dependencies

Requires the atproto Python package:

pip install atproto

Or with uv:

uv add atproto