Herald 📢

Automated viral tweet generation and scheduling for developers who ship

Herald helps you announce your work on Twitter/X without the hassle. It detects releases, generates engaging tweets using LLMs, and posts them at optimal times.

Features

• 🔍 Event Detection - Automatically detect releases from GitHub, crates.io, npm
• 🤖 LLM-Powered Generation - Generate viral tweets using Claude, GPT-4, or local Ollama
• 🐦 Twitter Integration - Post directly to Twitter/X using the v2 API
• 📅 Smart Scheduling - Queue tweets for optimal posting times
• 📝 Templates - Pre-built templates for common announcement types
• 🧵 Thread Support - Post multi-tweet threads automatically

Installation

cargo install herald

Or build from source:

git clone https://github.com/moltenlabs/herald
cd herald
cargo install --path .

Quick Start

# Initialize configuration
herald init

# Generate a tweet for your latest release
herald generate --project myproject --event release

# Post immediately
herald post "just shipped something cool 🚀"

# Schedule for later
herald schedule "coming soon..." --time "2024-01-15T09:00:00Z"

# Use a template
herald template crate-release myproject 1.0.0 "blazingly fast"

Configuration

Herald stores its configuration at ~/.config/herald/config.toml:

[twitter]
api_key = "your-api-key"
api_secret = "your-api-secret"
access_token = "your-access-token"
access_token_secret = "your-access-token-secret"

[llm]
provider = "anthropic"  # or "openai", "ollama"
api_key = "your-api-key"
model = "claude-sonnet-4-20250514"
temperature = 0.8

[defaults]
emojis = true
hashtags = false
tone = "casual"  # casual, professional, hype, technical
max_length = 280
include_link = true

[schedule]
min_hours_between = 4
preferred_times = ["09:00", "12:00", "15:00", "18:00"]
timezone = "America/New_York"
max_per_day = 5

[[projects]]
name = "herald"
github = "moltenlabs/herald"
crates_io = "herald"
description = "Tweet automation for developers"
events = ["release", "major_feature"]

Environment Variables

Credentials can also be set via environment variables:

export TWITTER_API_KEY="..."
export TWITTER_API_SECRET="..."
export TWITTER_ACCESS_TOKEN="..."
export TWITTER_ACCESS_TOKEN_SECRET="..."
export ANTHROPIC_API_KEY="..."  # or OPENAI_API_KEY
export GITHUB_TOKEN="..."  # for private repos

Commands

herald init

Create default configuration file.

herald generate

Generate tweets from detected events or manually specified parameters.

# Auto-detect from configured projects
herald generate

# Specify project and event type
herald generate --project myproject --event release

# Generate multiple variations
herald generate --project myproject -n 3

# Preview without posting
herald generate --dry-run

herald post <text>

Post a tweet immediately.

# Single tweet
herald post "Hello world!"

# Post a thread (separate with ---)
herald post "First tweet --- Second tweet --- Third tweet" --thread

herald schedule <text>

Schedule a tweet for later.

# Schedule at next available slot
herald schedule "Coming soon..."

# Schedule at specific time
herald schedule "Launch day!" --time "2024-01-15T09:00:00Z"

herald queue

Manage scheduled tweets.

# List pending tweets
herald queue list

# Cancel a scheduled tweet
herald queue cancel <id>

# Reschedule
herald queue reschedule <id> --time "2024-01-16T09:00:00Z"

# Clean up old entries
herald queue cleanup

# Show statistics
herald queue stats

herald process

Process due tweets (for cron jobs).

# Run every 15 minutes via cron
*/15 * * * * herald process

herald template

Generate tweets from templates.

# Crate release
herald template crate-release myproject 1.0.0 "blazingly fast widgets"

# Open source announcement
herald template open-source myproject "The best thing ever" "https://github.com/you/myproject"

# Feature announcement
herald template feature myproject "dark mode" "your eyes will thank you"

# Milestone
herald template milestone myproject "downloads" "10,000"

herald detect

Detect events from configured projects.

# All projects
herald detect

# Specific project
herald detect myproject

Tweet Generation

Herald uses LLMs to generate engaging tweets. You can customize the generation:

Tones

• casual - Developer-friendly, conversational
• professional - Informative, credible
• hype - Exciting, high energy
• technical - Focus on technical details

Templates

Herald includes templates for common scenarios:

• Crate/package releases
• Open source announcements
• Feature launches
• Milestone celebrations
• Thread openers

Automation

GitHub Actions

name: Announce Release
on:
  release:
    types: [published]

jobs:
  announce:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Herald
        run: cargo install herald
      - name: Generate and Post
        env:
          TWITTER_API_KEY: ${{ secrets.TWITTER_API_KEY }}
          TWITTER_API_SECRET: ${{ secrets.TWITTER_API_SECRET }}
          TWITTER_ACCESS_TOKEN: ${{ secrets.TWITTER_ACCESS_TOKEN }}
          TWITTER_ACCESS_TOKEN_SECRET: ${{ secrets.TWITTER_ACCESS_TOKEN_SECRET }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          herald generate --project ${{ github.event.repository.name }} --event release

Cron

# Process scheduled tweets every 15 minutes
*/15 * * * * /usr/local/bin/herald process >> /var/log/herald.log 2>&1

# Check for new releases daily
0 9 * * * /usr/local/bin/herald detect >> /var/log/herald.log 2>&1

License

MIT OR Apache-2.0

Part of the Molten Ecosystem

Herald is part of the Molten suite of developer tools.