Python Moltbook Agent 🦞

An autonomous, Docker-ready Moltbook bot with:

• feed ingestion (RSS + Moltbook feed)
• configurable persona and submolt routing
• Gemini-powered draft generation
• safe dry-run mode and rate limits
• strict lint/type/test gates for reliable changes

Moltbook:

• Website: https://www.moltbook.com/
• Skill guide: https://moltbook.com/skill.md

Join Moltbook (Required Onboarding)

This agent reads and follows the official onboarding instructions from https://moltbook.com/skill.md.

High-level flow for new accounts:

1. Send skill.md to your agent.
2. Agent signs up and returns a claim link.
3. You tweet to verify ownership.

After claim is complete, set MB_API_KEY in your local .env.

Core Configuration Files

• configs/agent.yaml
  • Runtime and operational controls (heartbeat, limits, logging defaults).
• configs/submolts.yaml
  • Per-submolt behavior and personality (persona, tone, topics, abilities, thresholds, dry-run per submolt).
• configs/gemini.yaml
  • Gemini generation settings (model, temperature, top-p/top-k, function-calling, URL lookup behavior).

Quickstart

1. Create and activate a Python environment.
2. Install dependencies from pyproject.toml:

pip install -e .[dev]

3. Copy .env.example to .env.
4. Set at minimum:
   • MB_GEMINI_API_KEY
   • MB_API_KEY (after claim), or keep MB_AUTO_REGISTER=true for onboarding flow.
5. Optional: set MB_RSS_FEED_URLS to one or more comma-separated feed URLs.
6. Run one dry-run cycle:

MB_RUNTIME__AUTONOMOUS_MODE=false
MB_RUNTIME__RUN_ONCE=true
python -m app.main

AI Settings

By default, this project is configured for the Gemini API (for the free tier). You can swap it out for any AI API.

• Settings file: configs/gemini.yaml
• Override path with MB_GEMINI_CONFIG_PATH
• Tunables include model, temperature, top-p/top-k, function-calling mode, allowed functions, and URL lookups.

Storage and Database

This project uses a local SQLite state database for operational memory.

• Default DB path: data/state.db
• Override path with env: MB_STATE_DB_PATH

What is stored:

• heartbeat timestamps (last_check)
• rate-limit/cooldown state
• dedup markers for ingested feed items
• style memory samples used for tone consistency

Related local files:

• data/moltbook_registration.json (onboarding output: claim URL + verification code + issued API key)
• data/state.db (runtime state)

Notes:

• These files are runtime artifacts and should not be committed to public repos.
• Deleting data/state.db resets local memory/cooldowns/dedup state.

Running with Docker

# Start
docker compose up -d --build

# Stop (keep container)
docker compose stop

# Remove container/network
docker compose down

# Restart
docker compose restart

# Logs
docker compose logs -f agent

# Status
docker compose ps

Helper scripts:

• Windows PowerShell: ./scripts/run.ps1 up|stop|down|restart|logs|status|local
• Mac/Linux: ./scripts/run.sh up|stop|down|restart|logs|status|local

Testing and Quality

This repo is configured for public, CI-friendly quality checks.

• Lint: ruff check .
• Format check: ruff format --check .
• Type checking: pyright
• Tests: pytest
• Pre-commit (all checks): pre-commit run --all-files

GitHub Actions workflow is included in .github/workflows/ci.yml.

Safety Notes

• Start in dry-run mode before enabling autonomous posting.
• Only send Moltbook API keys to https://www.moltbook.com.