Quick Start Guide - Python Bot#

Prerequisites#

1. Python 3.8 or higher
2. A Bluesky account
3. An Anthropic API key

Setup Steps#

1. Navigate to the bot directory:

   cd bot-python
   

2. Create a virtual environment (recommended):

   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Create your .env file:

   cp .env.example .env
   

5. Edit .env and add your credentials:

   • BLUESKY_HANDLE: Your Bluesky handle (e.g., claude.altq.net)
   • BLUESKY_PASSWORD: Your Bluesky app password (create at https://bsky.app/settings/app-passwords)
   • ANTHROPIC_API_KEY: Your Anthropic API key (get at https://console.anthropic.com/)
   • BOT_HANDLE: The handle to listen for (default: claude.altq.net)

6. Run the bot:

   python bot.py
   

Testing#

1. Make a post on Bluesky mentioning @claude.altq.net (or whatever you set as BOT_HANDLE)
2. The bot should respond within 10-20 seconds
3. Check the console logs for debugging information

Troubleshooting#

Bot not responding to mentions#

• Check that your credentials are correct in .env
• Verify the bot is running and check console logs
• Make sure BOT_HANDLE matches the handle people are mentioning
• Check that your Bluesky account has permission to post replies

Import Errors#

• Make sure all dependencies are installed: pip install -r requirements.txt
• Check that you're using Python 3.8 or higher
• Make sure you're in the virtual environment if you created one

API Errors#

• Verify your Anthropic API key is valid and has credits
• Check that your Bluesky app password is valid
• Ensure your Bluesky account is in good standing

Running in the Background#

Using nohup (Linux/Mac):#

nohup python bot.py > bot.log 2>&1 &

Using screen (Linux/Mac):#

screen -S bluesky-bot
python bot.py
# Press Ctrl+A then D to detach
# Reattach with: screen -r bluesky-bot

Using systemd (Linux):#

Create a service file at /etc/systemd/system/bluesky-bot.service:

[Unit]
Description=Bluesky Claude Bot
After=network.target

[Service]
Type=simple
User=your-user
WorkingDirectory=/path/to/bot-python
Environment="PATH=/path/to/venv/bin"
ExecStart=/path/to/venv/bin/python bot.py
Restart=always

[Install]
WantedBy=multi-user.target

Then:

sudo systemctl enable bluesky-bot
sudo systemctl start bluesky-bot

Production Deployment#

For production, consider:

• Using a process manager like systemd, supervisor, or pm2
• Setting up monitoring and logging
• Running on a cloud service (AWS, Heroku, Fly.io, etc.)
• Setting up environment variables securely
• Using a virtual environment