📚 Documentation

Complete guide to setting up and using Social Scheduler for social media management.

Beta · Found a bug? Report on GitHub

Getting Started

Social Scheduler runs locally on your machine. Here's how to get it running:

Option 1: Download Desktop App

The easiest way — download the pre-built app for your platform:

1. Go to Releases
2. Download the file for your OS (macOS, Windows, or Linux)
3. Install and run

xattr -c "/Applications/Social Scheduler.app"

Option 2: Run from Source

# Clone the repository
git clone https://github.com/tervahagn/social-scheduler.git
cd social-scheduler

# Install dependencies
cd backend && npm install
cd ../frontend && npm install

# Configure
cp .env.example .env
# Edit .env with your OpenRouter API key

# Run
./start.sh

Open http://localhost:3000 in your browser.

Quick Post

Quick Post lets you write once and publish to multiple platforms instantly.

1. Click "Quick Post" in the sidebar
2. Write your content
3. Select platforms (LinkedIn, Twitter, Facebook, etc.)
4. See real-time character counters for each platform
5. Click "Publish Now" or "Schedule" to pick a date

Calendar & Scheduling

The Calendar shows all your scheduled and published posts in one view.

• Purple — Scheduled posts (waiting to be published)
• Green — Published posts
• Click any post to view or edit it
• Switch between Month, Week, and Day views

When you schedule a post, Social Scheduler sends it to your Make.com Data Store. The Publisher scenario (running on a schedule) picks it up and posts it at the right time.

Brief Mode

Brief mode uses AI to generate platform-specific posts from a single idea.

1. Click "New Brief" in the sidebar
2. Write your main idea or paste an article
3. Select which platforms you want posts for
4. Click "Generate" — AI creates a unique post for each platform
5. Edit any post if needed
6. Approve and publish or schedule

Each platform gets content optimized for its format: LinkedIn gets professional tone, Twitter gets short punchy text, Instagram gets hashtags, etc.

Prompts & Brand Voice

Social Scheduler uses a three-tier prompt system to generate content that sounds like you, optimized for each platform.

🎯 Master Prompt (Brand Voice)

This is your brand's personality — how you sound across all content. It's written once and applied to everything you generate.

Define things like:

• Tone: professional, casual, witty, authoritative
• Style: use of emojis, sentence length, vocabulary level
• Perspective: first person ("I/we") or third person
• Values: what your brand stands for

📱 Platform Prompts (Channel Customization)

Each platform has its own prompt that adapts content to the channel's unique format and audience expectations:

• LinkedIn — Professional tone, structured paragraphs, thought leadership angle
• Twitter/X — Punchy hooks, concise points, thread-friendly
• Instagram — Visual context, storytelling, hashtag strategy
• Reddit — Authentic, conversational, no marketing-speak
• Facebook — Community-focused, shareable, engaging questions
• YouTube — Descriptive, keyword-rich, call-to-action

You can customize these in Settings → Platform Prompts.

📝 Brief Input (Content Prompt)

This is what you write when creating a new brief — your idea, article, announcement, or any source material. The AI combines:

Your Brief Input (the idea)
        ↓
    Master Prompt (brand voice)
        ↓
    Platform Prompt (channel rules)
        ↓
    Final post for each platform

This layered approach ensures every post sounds like your brand while being native to each platform.

Make.com Integration

Social Scheduler uses Make.com (formerly Integromat) for actual publishing. This keeps the app simple and avoids dealing with constantly changing social media APIs.

Architecture: Two Scenarios

You need two scenarios in Make.com:

1. Receiver Scenario — Receives posts from Social Scheduler via webhook, saves to Data Store
2. Publisher Scenario — Runs on a schedule, reads from Data Store, posts to platforms

Step 1: Create Data Store

1. In Make.com, go to Data Stores → Create a new one
2. Name it "Social Scheduler Posts"
3. Add these fields:
   • post_id (Text) — Primary key
   • platform (Text)
   • content (Text)
   • media_url (Text)
   • scheduled_at (Date)

Step 2: Create Receiver Scenario

1. Create new scenario
2. Add trigger: Webhooks → Custom Webhook
3. Copy the webhook URL
4. Paste it in Social Scheduler Settings → Webhook URL
5. Add module: Data Store → Add/Replace a Record
6. Map the incoming fields to your Data Store
7. Turn ON the scenario

Step 3: Create Publisher Scenario

1. Create new scenario
2. Add trigger: Schedule (every 5 minutes)
3. Add module: Data Store → Search Records
4. Filter: scheduled_at less than or equal to now
5. Add Router to branch by platform
6. For each branch, add the platform module (LinkedIn, Facebook, etc.)
7. After each platform, add: Data Store → Delete a Record
8. Turn ON the scenario

OpenRouter & AI

Social Scheduler uses OpenRouter for AI content generation. OpenRouter gives you access to GPT-4, Claude, Llama, Gemini, and many other models.

Setup

1. Create account at openrouter.ai
2. Go to Settings → API Keys → Create new key
3. Copy the key (starts with sk-or-)
4. Paste in Social Scheduler Settings → OpenRouter API Key
5. Choose your preferred model

Recommended Models

• claude-3.5-sonnet — Best quality, good for professional content
• gpt-4-turbo — Reliable, widely tested
• llama-3.1-70b — Good free option
• gemini-pro — Fast and capable

Troubleshooting

"App is damaged" on macOS

When you download an app from anywhere other than the Mac App Store, macOS adds an extended attribute called com.apple.Quarantine. This is Gatekeeper's way of protecting you — but for apps like Social Scheduler that aren't notarized by Apple, it shows the frustrating "damaged and can't be opened" error.

The fix is simple — remove the quarantine attribute:

xattr -c "/Applications/Social Scheduler.app"

That's it! Launch the app and enjoy. 🚀

Backend not starting

Check if port 3001 is already in use:

lsof -i :3001
# If something is using it, kill it:
kill -9 [PID]

Posts not appearing in Make.com

• Check that the webhook URL in Settings is correct
• Make sure the Receiver scenario is turned ON
• Check Make.com scenario history for errors

AI generation fails

• Verify your OpenRouter API key is correct
• Check if you have credits in OpenRouter
• Try a different model