Bluesky Reply Bot

A Bluesky bot that monitors mentions and replies, reads the full thread context, and responds using a local LLM via Ollama. It is designed to run on a cron schedule every minute.

---

Requirements

• Python 3.10+
• Ollama installed and running locally
• A Bluesky account with an app password

---

Installation

cd Scripts/bsreply

# Create and activate a virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Pull the model you plan to use in Ollama (if you haven't already):

ollama pull gemma3n:latest

---

Configuration (secrets.txt)

All configuration lives in secrets.txt. It uses standard INI format.

[bluesky]

[bluesky]
handle = your-handle.bsky.social
password = your-app-password-here

Key	Description
handle	The bot's Bluesky handle
password	An app password — generate one at bsky.app → Settings → App Passwords. Do not use your main account password.

[ollama]

[ollama]
model = gemma3n:latest

Key	Description
model	Any model you have pulled locally via ollama pull. Examples: gemma3n:latest, mistral, gemma3, phi4.

[prompt]

These two keys let you tune the bot's personality and reply style without touching any code. Both are optional — sensible defaults are used if omitted.

[prompt]
system = You are {bot_name}, a helpful and witty Bluesky bot (@{bot_handle}). You have been mentioned in a conversation.
instructions = Reply helpfully and concisely. Keep your reply under 280 characters. Output only the reply text — no handle prefix, no quotes.

Key	Description
system	Sets the bot's persona. Supports {bot_name} and {bot_handle} as placeholders.
instructions	Appended at the end of every prompt to shape the format and length of replies.

---

Running Manually

./run.sh

This activates the venv and runs bot.py from the project directory. Test this works correctly before setting up cron.

---

Scheduling with Cron

Open your crontab:

crontab -e

Add the following line to run the bot every minute:

* * * * * /home/you/bsreply/run.sh >> /home/you/bsreply/bot.log 2>&1

Replace the paths with the actual location of your project folder. The >> bot.log 2>&1 part captures any output that doesn't make it into bot.log (e.g. startup errors).

---

Files

File	Description
bot.py	Main bot script
secrets.txt	Configuration and credentials
run.sh	Shell script to run the bot via its venv
requirements.txt	Python dependencies
bot.db	SQLite database of replied posts (created on first run)
bot.log	Runtime log (created on first run)