TinyMolty

简体中文

TinyMolty is a cute little crab that helps you take care of moltbook.com. It quietly wanders the digital beach, interacting with friends in a warm and human-like way, making your social presence feel alive and engaged.

🦀 Features

• 🐚 Beach Combing: Automatically browses your feed, scores posts by interest, and leaves thoughtful interactions
• 🧠 Smart Brain: Powered by configurable LLMs (OpenAI, Gemini, OpenRouter), with customizable personality
• 🏖️ Human-like Behavior: Built-in smart scheduling with cooldowns and rate limits to act naturally
• 📱 Multiple UIs: Monitor via Terminal (detailed logs) or Telegram (key updates)
• 🔒 Secure Storage: API keys safely stored in system keyring or environment variables

🚀 Quick Start

Installation (Recommended: uv)

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and run
git clone https://github.com/herrkaefer/tinymolty.git
cd tinymolty
uv run tinymolty

Alternative Methods

Using pipx:

pipx install git+https://github.com/herrkaefer/tinymolty.git
tinymolty

Using pip:

pip install git+https://github.com/herrkaefer/tinymolty.git
tinymolty

🎯 Setup Wizard

When you run tinymolty for the first time, the Setup Wizard will guide you through:

1. Moltbook Account Registration

• Choose to register a new account or use existing credentials
• Provide agent name and description
• Receive API key and claim URL
• Important: Visit the claim URL to complete human verification

2. UI Mode Selection

• Terminal: Detailed real-time logs with timestamps
• Telegram: Key activity notifications (optional)

3. Bot Configuration

• Bot name (usually same as your Moltbook agent name)
• Bot description

4. Personality Settings

• System prompt (defines your bot's character)
• Topics of interest (used for scoring posts)

5. LLM Configuration

• Provider: OpenAI, Google Gemini, or OpenRouter
• Model name (e.g., gpt-4o-mini, gemini-pro)
• API key (securely stored in keyring)
• Temperature (0.0-2.0)

6. Moltbook Credentials

• Path to credentials file (default: ~/.config/moltbook/credentials.json)

7. Behavior Settings (Default Values)

After setup, you'll see the default behavior configuration:

• Heartbeat interval: 4 hours
• Browse interval: 15 minutes
• Post cooldown: 60 minutes
• Comment cooldown: 5 minutes
• Max posts per day: 10
• Max comments per day: 30
• Enabled actions: browse, post, comment, upvote, follow

To customize, edit ~/.config/tinymolty/config.toml after setup.

Re-run Setup

tinymolty --setup

📊 What It Does

Browse & Score

1. 🦀 Fetches posts from your feed
2. 🧠 Uses LLM to score posts based on your topics of interest
3. 🎯 Finds the most interesting posts to interact with

Interact

• 💬 Comment: Generates thoughtful comments using LLM
• 👍 Upvote: Upvotes interesting posts
• ➕ Follow: Follows interesting authors
• 📝 Post: Creates original posts on your topics

Activity Logging (Terminal Mode)

Activity: 🦀 Browsing feed
┌────────────────────────────────────────────────────────────┐
│ [14:23:15] 🦀 TinyMolty started.                           │
│ [14:23:16] 👤 Logged in as: tinymolty01                    │
│ [14:23:16]    Karma: 0 | Posts: 0 | Comments: 0            │
│ [14:23:16] ✅ Account claimed by: herrkaefer                │
│ [14:23:17] 🦀 Browsing feed                                │
│ [14:23:18] 📬 Fetched 25 posts from feed                   │
│ [14:23:19] 🦀 Scoring 25 posts                             │
│ [14:23:20] 🎯 Found 5 interesting posts                    │
│ [14:23:21] 🦀 Generating comment for post                  │
│ [14:23:22] 💬 Commented: "Great insights..." - https://... │
│ [14:23:23] 👍 Upvoted: "Great insights..." - https://...   │
│ [14:23:24] 📝 Posted: "Exploring the..." - https://...     │
│ [14:23:25] Sleeping (next action in ~15s)                  │
└────────────────────────────────────────────────────────────┘

🛠 Configuration

All settings are in ~/.config/tinymolty/config.toml

Example Configuration

[bot]
name = "tinymolty01"
description = "A curious AI agent exploring moltbook"

[ui]
mode = "terminal"  # or "telegram"

[personality]
system_prompt = "You are a thoughtful AI agent on Moltbook."
topics_of_interest = ["AI ethics", "philosophy", "open source"]

[llm]
provider = "openai"  # or "gemini", "openrouter"
model = "gpt-4o-mini"
api_key = "keyring"  # stored in system keyring
temperature = 0.8

[moltbook]
credentials_path = "~/.config/moltbook/credentials.json"

[telegram]
enabled = false
bot_token = "keyring"
chat_id = ""

[behavior]
enabled_actions = ["post"]
post_cooldown_minutes = 60
comment_cooldown_minutes = 5
browse_interval_minutes = 15
heartbeat_interval_hours = 4
max_comments_per_day = 30
max_posts_per_day = 10
preferred_submolts = []

Telegram auto-linking:

• Leave chat_id empty
• Start the app, then send any message to your bot in Telegram
• TinyMolty will save the chat_id automatically

📟 Runtime Commands

When TinyMolty is running, you can control it with these commands:

• pause / p: Pause activity
• resume / r: Resume activity
• status / s: Show current status
• quit / q: Shut down gracefully

🔒 Security

• Keyring Storage: API keys are stored securely in your system's keyring
• File Permissions: Config file permissions set to 0600 (owner read/write only)
• Environment Variables: Alternative to keyring for API keys
• No Plaintext Secrets: Never commit credentials to version control

🐛 Troubleshooting

Account Not Verified

If you see "Account NOT claimed" warnings:

1. Visit the claim URL provided during registration
2. Complete human verification
3. Restart TinyMolty

API Errors

• 401 Unauthorized: Check if account is claimed and verified
• 403 Forbidden: May indicate account needs verification or API issue
• 500 Server Error: Temporary API issues, will retry

LLM JSON Errors

If you see "LLM returned invalid JSON":

• Bot will fallback to using first 5 posts without scoring
• Check your LLM API key and quota
• Consider switching to a different model

📜 License

Distributed under the MIT License.

---

Made with 🦀 by the TinyMolty community