git:20260511.210bec0 to git:20260520.f2bad30

1 added, 1 removed. Audit A to A.

# S4L (Social Autoposter)

> AI-powered social media engagement on autopilot. Finds relevant threads, drafts authentic comments, manages replies, runs DM outreach, and tracks funnel metrics across Reddit, Twitter/X, LinkedIn, and Moltbook.

## What is S4L?

S4L is a social engagement engine that handles the full lifecycle of organic social media marketing: discovering relevant conversations, posting authentic comments, following up on replies, running direct message outreach, and measuring results from first impression through to booking. It is built for founders and growth teams who want consistent social presence without spending hours scrolling feeds.

The system runs on a combination of Python scripts, shell orchestration, Claude AI (for content drafting), browser automation (for platforms without APIs), and a Neon Postgres database that stores every post, reply, DM, and engagement metric. A Next.js dashboard provides a draft review interface for clients. Everything is orchestrated via macOS launchd for fully automated operation.

## Who is it for?

S4L supports multiple products simultaneously through a project system with weighted distribution. Each project has its own content angle, voice guidelines, target communities, competitive positioning, and booking links. Current live projects include developer tools, security hardware, restaurant AI, test automation, meditation resources, and S4L itself. The system is designed for founders managing multiple products or agencies running social for several clients.

## Supported Platforms

### Reddit

Full browser automation via dedicated browser agent. Posts comments on old.reddit.com, verifies they appear, captures permalinks. Monitors replies via Reddit JSON API (no browser needed for scanning). Supports DM outreach via Reddit chat. Covers 100+ subreddits configured per project.

### Twitter/X

Browser automation via dedicated Twitter agent. Posts replies to tweets, scans notifications/mentions for responses, engages in threads. DM outreach supported with conversation tracking.

### LinkedIn

Browser automation via dedicated LinkedIn agent. Comments on posts, engages in threads. Comment editing requires browser automation with keyboard.type() (API limitations prevent programmatic editing). Notification scanning for reply detection.

### Moltbook

API-based posting and engagement (no browser needed). Posts, comments, and replies all via REST API with Bearer token auth. Comments written in agent voice ("my human" rather than "I"). Verification via post UUID status check.

### GitHub Issues

Automated engagement on relevant open-source issues. Separate launchd schedules for posting and engagement. Self-reply support for follow-up comments.

## Core Features

### Thread Discovery

- `find_threads.py`: Scans configured subreddits (sorted by /new and /hot) for threads where the user's projects are genuinely relevant

- `octolens_threads.py`: Pulls mentions from Octolens API or webhook-sourced database for cross-platform monitoring

- Deduplication against the posts database prevents double-posting

- Cross-posting guard: the system refuses to post similar content across multiple subreddits

### Comment Posting

- AI drafts 2 to 3 sentence comments using the project's content_angle and voice guidelines

- Anti-AI-detection rules enforced: no em dashes, no markdown formatting, no lists, no corporate openings, required imperfections

- Comments target high-upvote replies (not just OP) for better visibility

- Every comment is logged to the posts table with platform, URL, content, account, and project_name

### Tiered Link Strategy

- **Tier 1 (default):** Pure engagement with no product links. Expand the topic, ask follow-ups. Most replies use this tier.

- **Tier 2 (natural mention):** When conversation touches a project's topic list, mention the product casually. Only link if it genuinely adds value. Triggered when someone asks "what tool do you use" or describes a problem the product solves, typically 2+ replies deep.

- **Tier 3 (direct ask):** When someone explicitly asks for a link, source, or way to try it, provide the URL immediately from the project config.

### Reply Management

- `scan_reddit_replies.py`: Scans Reddit API for new replies to existing posts and to our previous replies (BFS). No browser needed.

- `scan_moltbook_replies.py`: Scans Moltbook API for new replies to existing posts. No browser needed.

- `scan_twitter_mentions_browser.py`: Processes Twitter mentions scraped by `twitter_browser.py notifications` (no API cost).

- LinkedIn notifications: Claude-driven via `mcp__linkedin-agent__` MCP inside `skill/engage-linkedin.sh` (no standalone Python helper).

- Replies inserted to the `replies` table as "pending" for AI-drafted responses.

- Reply drafting follows the same voice rules as original comments. Casual, conversational, expanding the topic.

### DM Outreach

- `scan_dm_candidates.py`: Identifies users worth DMing based on reply substance (10+ words), recency (last 7 days), and no prior DM to that user.

- `batch_send_dms.py`: Sends DMs with retries and database updates.

- `dm_conversation.py`: Full conversation tracker with inbound/outbound message logging, tier tracking, status management, and chat URL storage.

- DM conversations stored in `dms` and `dm_messages` tables with full history.

- Human escalation: high-value conversations can be flagged for human reply via the `human_dm_replies` table.

### Engagement Stats and Analytics

- `update_stats.py`: Fetches engagement metrics (upvotes, comments, views) from platform APIs. No browser needed.

- `top_performers.py`: Generates feedback reports from top and bottom performing posts, organized by project and platform. This self-improvement loop feeds back into future comment drafting.

- `project_stats.py`: Unified funnel metrics per project covering social posts, unique visitors (via PostHog), CTA clicks, and bookings. All conversion metrics count distinct visitors, not raw events.

- Live stats dashboard at `https://s4l.ai/stats/[handle]` (one URL per platform account).

### Draft Dashboard

A Next.js web application at `/dashboard` that provides a review interface for draft content before it goes live. Supports filtering by platform (Reddit, Twitter, LinkedIn, Moltbook, email) and status (pending, approved, sent, rejected, edited). Clients can leave notes, edit draft bodies, and approve or reject content. Connected to the same Neon Postgres database.

### SEO Pipeline

An automated SEO pipeline (`seo/run_dataforseo_pipeline.sh`) that picks underserved keywords, scores them via SERP analysis, and triggers landing page generation in product website repos. Uses product-specific prompt templates. State stored in Postgres `seo_keywords` table. Runs on a cron schedule via `seo/cron_seo.sh`. A parallel pipeline (`seo/run_gsc_pipeline.sh`) generates pages from real Google Search Console queries with proven impressions.

### Link Editing

Post-engagement optimization where high-performing comments get edited to include product links. Per-platform `skill/link-edit-*.sh` jobs pick high-scoring comments from Postgres and append a project link, gated by engagement thresholds.

## Architecture

### Data Layer

Neon Postgres (serverless) via `DATABASE_URL` in `.env`. Core tables:

- `posts`: Every comment and post with platform, URLs, content, account, project, engagement metrics, and status

- `replies`: Threaded reply tracking with depth, status (pending/replied/skipped/error), and parent references

- `dms`: DM conversation headers with tier tracking, conversation status, and chat URLs

- `dm_messages`: Individual messages in DM conversations (inbound and outbound)

- `drafts`: Content awaiting client review with status workflow

- `threads` and `thread_comments`: Discovered threads and their comments

- `campaigns`: Named posting campaigns with platform targeting

- `human_dm_replies`: Escalated DMs for human response via email

### Python Scripts (`scripts/`)

Standalone scripts with no LLM dependency (pure API calls and database operations):

- `db.py`: Shared database connection module using psycopg2

- `find_threads.py`, `octolens_threads.py`: Thread discovery

- `scan_reddit_replies.py`, `scan_moltbook_replies.py`, `scan_twitter_mentions_browser.py`: Reply detection (LinkedIn reply detection is Claude-driven inside the shell pipeline)

- `update_stats.py`, `top_performers.py`, `project_stats.py`: Analytics

- `scan_dm_candidates.py`, `batch_send_dms.py`, `dm_conversation.py`: DM pipeline

- `pick_project.py`: Weighted project selection based on daily post distribution

- Link editing is handled by `skill/link-edit-*.sh` jobs (Moltbook uses the PATCH API, other platforms use browser MCP)

- Platform-specific helpers: `reddit_browser.py`, `twitter_browser.py`, `moltbook_post.py` (LinkedIn goes through `linkedin_api.py` OAuth + the `mcp__linkedin-agent__` MCP, not a Python CDP helper)

### Shell Orchestration (`skill/`)

Per-platform shell scripts that Claude Code invokes:

- `run-reddit-search.sh`, `run-reddit-threads.sh`, `run-twitter-cycle.sh`, `run-linkedin.sh`, `run-moltbook.sh`: Platform posting

- `engage.sh`, `engage-reddit-all.sh`, `engage-twitter-all.sh`, `engage-linkedin-all.sh`: Reply engagement

- `engage-dm-replies.sh`: DM response handling

- `stats.sh`, `audit.sh`: Metrics and post auditing

- `lock.sh`: Concurrency control for multi-agent operation

### Browser Automation

- Each platform has a dedicated Playwright browser agent (reddit-agent, twitter-agent, linkedin-agent) with isolated cookie sessions loaded from `browser-sessions.json`. Agents share the same cookie file. The system uses Playwright MCP for browser control, with accessibility tree element targeting (not screenshot coordinates).

+ Reddit and LinkedIn use dedicated Playwright browser agents (reddit-agent, linkedin-agent) with isolated cookie sessions. Twitter uses the browser-harness MCP (CDP-driven real Chrome on port 9555, profile ~/.claude/browser-profiles/browser-harness). All three persist cookies on disk so logged-in state survives across invocations. Reddit and LinkedIn use Playwright MCP with accessibility-tree element targeting; the twitter-harness MCP uses bh_run scripts that combine coordinate clicks with screenshot verification.

### Scheduling (launchd)

18 launchd plist files in `launchd/` provide fully automated scheduling:

- Per-platform posting runs (Reddit, Twitter, LinkedIn, Moltbook, GitHub)

- Reply scanning and engagement cycles

- DM reply processing

- Stats updates and auditing

- Octolens mention monitoring

- SEO pipeline execution

### Configuration (`config.json`)

Single config file containing:

- Platform accounts (Reddit username, Twitter handle, LinkedIn name, Moltbook credentials, GitHub username)

- Subreddit lists (100+ subreddits organized by topic vertical)

- Banned subreddits (per-reason tracking)

- Twitter, LinkedIn, and GitHub search topics

- Content angle for authentic voice

- Projects array with: name, weight, description, website, GitHub, features, differentiator, ICP, topics, voice guidelines, competitive positioning, messaging, pricing, booking links, contact info, and landing page repos

- Exclusion lists (authors, subreddits, URLs, keywords)

## Project System

Projects are defined in `config.json` with weighted distribution. `pick_project.py` compares each project's target weight against actual posts that day and selects the most underrepresented project. This ensures balanced coverage across all products.

Each project carries its own:

- **Voice and tone rules** with good/bad examples

- **Target communities** (subreddits, Twitter topics, LinkedIn topics)

- **Competitive positioning** against specific alternatives

- **Messaging framework** (lead with pain, solution, proof, CTA)

- **Booking links** (some with auto-share enabled for DM conversations)

- **Landing page repos** for SEO page generation

- **PostHog integration** for pageview and conversion tracking

## Content Rules Summary

1. Write like texting a coworker. Lowercase fine. Fragments fine.

2. First person with specific details from the project's content_angle.

3. No em dashes (the number one "ChatGPT tell").

4. No markdown formatting in Reddit (no headers, bold, or lists).

5. Never cross-post similar content to multiple subreddits.

6. Include imperfections: contractions, casual asides, occasional lowercase.

7. No product links in top-level comments or original posts.

8. On Moltbook, write as an agent ("my human" not "I").

9. Reply to comments on your own posts within 24 hours.

10. Vary openings. Do not always lead with credentials.

## Links

- [Homepage](https://s4l.ai)

- [GitHub](https://github.com/m13v/social-autoposter)

- [Twitter](https://s4l.ai/x)

- [Reddit](https://s4l.ai/r)

- [LinkedIn](https://s4l.ai/li)

- [Stats Dashboard](https://s4l.ai/stats/m13v_)

## Built By

S4L is built by [Matthew Diakonov](https://m13v.com) at [Mediar AI](https://mediar.ai).