Start from a template

Markdown version

Download a small starter, inspect its code, and run it on your own computer or in your own GitHub repository. Bluesky.bot does not run it or store its app password.

Choose a language

Both starters use the official/community SDKs shown below, a fixed dependency version and MIT-0 licensing. They include sample posts, tests and dormant workflows. These are downloads from this site; separate GitHub template repositories and bsbot init have not been released.

Try the dry run

Extract the archive. A dry run is the default and needs no credentials: it does not sign in or contact Bluesky. The README in each archive gives the complete commands.

bash
# TypeScript: Node.js 24 + pnpm 12.18.0
cd bluesky-bot-typescript
pnpm install --frozen-lockfile
pnpm start
bash
# Python 3.13
cd bluesky-bot-python
python -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements.txt
python bot.py

Publish from your own repository

Review posts.txt, create an app password while signed in as the bot, and set BLUESKY_HANDLE and BLUESKY_APP_PASSWORD as secrets in your own repository. Set DRY_RUN=false only when ready. The sample schedule runs every 30 minutes with no overlap. GitHub can delay schedules and disables public-repository schedules after 60 days without activity.

Replies and rate limits

The first live run adds the Automation self-label with compare-and-swap, preserving your profile. Replies are off by default. If you enable them, only unread direct mentions and replies are considered; self-labelled bot authors, your own account, blocks and mutes are skipped. Five replies per run at most. A 429 or other failure stops the run; review a failed partial run before retrying.

Sync your listing

Edit bluesky-bot.json yourself. A listing-only deploy token, ideally limited to this bot, goes in BSBOT_TOKEN; set BOT_DID too. The included workflow sends the creator-approved file through the HTTP listing API. No unpublished CLI command is required.

Learn the pieces