An autonomous engagement loop that finds relevant threads on Reddit and Discord, drafts value-add comments graded by an LLM, and posts only when quality clears the bar — with a hard kill switch and per-platform rate limits baked in.
For every relevant thread found, the outreach service calls the LLM with a persona system block and the thread context, generates a comment draft, then self-grades it on a 0–1 scale. Only drafts scoring ≥ 0.7 advance to the posting stage. Drafts below threshold are logged but discarded, keeping the quality bar consistent without manual review of every candidate.
Hard caps enforce responsible cadence: one post per 30 minutes per platform, eight posts per 24 hours per platform. A single POST to /api/social-outreach/kill stops all activity immediately. The global setting social_outreach_enabled defaults to false — nothing runs until you explicitly enable it. Two consecutive servo failures on a task automatically abort the run and log the reason.
Every action — drafted, posted, aborted, rejected — is written to an append-only data/social_outreach/audit.jsonl file and a SocialOutreachLog database row. The audit endpoint returns the last 200 events so you can review exactly what the agent said, where it said it, and whether the post went through. Nothing is hidden.
A curated OUTWARD_FACING_SYSTEM_BLOCK instructs the LLM on tone: direct, competent, occasionally funny, never bot-like, never leading with a promotional link. The persona is grounded in Guaardvark's actual feature set via a FEATURE_BLURBS dictionary, so the agent mentions specific capabilities (local RAG, video generation, voice chat) in context rather than generic marketing copy.
Social Outreach is designed around a single constraint: every comment posted must provide genuine value to the thread it enters. The agent searches configured subreddits and Discord channels for posts matching a relevance keyword set — terms like ollama, comfyui, local-ai, self-host, stable-diffusion, rag — and only engages with threads where Guaardvark's capabilities are genuinely relevant. It reads the original post and the top comments before drafting, so the reply is contextual rather than canned.
The architecture mirrors the rest of Guaardvark's automation stack. A Celery Beat scheduler triggers outreach tasks on a configurable interval. Each task calls /api/social-outreach/draft-comment, which routes through unified_chat_engine.chat(mode="outreach") — the same chat engine used everywhere else in the platform, but with the outreach persona prepended to the system prompt. The result is a comment draft plus a self-assessed quality score. The kill switch and cadence gate are checked before any network write; if either check fails, the event is logged as aborted and the task exits cleanly.
Reddit engagement uses Guaardvark's Playwright-powered browser automation layer against the user's own logged-in Firefox session on the virtual display. Discord uses the Discord API directly via the bot integration, so no browser servo is required for that platform. Facebook is explicitly deferred from the initial release — the servo failure rate on Facebook's dynamic DOM was judged too high for reliable unattended operation. The first night of operation is designed as a validation pass: review the audit log in the morning, adjust the target subreddit list and quality threshold, then re-enable for the next cycle.
Service architecture. The outreach system lives in backend/services/social_outreach/. persona.py holds the outward-facing system block, per-feature blurbs, relevance keywords, and platform share-link templates. audit.py writes both to data/social_outreach/audit.jsonl (fsync'd append-only) and to the SocialOutreachLog SQLAlchemy model. kill_switch.py uses Redis to track posts-per-window counts alongside the global enable flag stored as a Setting row. The API blueprint at backend/api/social_outreach_api.py exposes GET /status, POST /kill, POST /enable, GET /audit, and the POST /draft-comment endpoint that the loops call internally.
Loop implementations. The Reddit outreach loop (reddit_outreach.py) uses browser_automation_service.py (Playwright) to navigate subreddits, extract thread content via BrowserExtractTool, check subreddit rules for no-self-promo flags before engaging, and type/submit comments through browser recipes. The Discord loop is a discord.py cog that polls channel history every 10 minutes, filters against the relevance keywords, and calls the draft-comment endpoint before replying via the Discord API. Both loops gate every action through the kill switch and cadence checker. Celery tasks in backend/tasks/social_outreach_tasks.py wrap both loops for scheduler-driven invocation.
# Enable the outreach loop
curl -X POST http://localhost:5000/api/social-outreach/enable
# Kill immediately
curl -X POST http://localhost:5000/api/social-outreach/kill
# Check status + cadence caps
curl http://localhost:5000/api/social-outreach/status
# Review last 50 actions
curl "http://localhost:5000/api/social-outreach/audit?limit=50"Configure the Reddit loop with subreddits like r/LocalLLaMA, r/StableDiffusion, and r/selfhosted. The agent monitors for threads where people are asking about running models locally or looking for all-in-one platforms, drafts a helpful comment describing how Guaardvark solves the problem, grades it, and posts if quality passes. You get compounding organic reach without manually watching every subreddit.
Point the Discord cog at channels in AI-focused servers where members discuss Ollama integrations, ComfyUI workflows, or self-hosted tooling. The bot polls channel history, finds relevant threads, and replies with specific Guaardvark feature mentions grounded in the actual conversation context. The Discord API path requires no browser servo, making it the most reliable platform for unattended operation.
Run with is_supervised=true to shift from autonomous posting to a draft queue. The agent generates and grades comments but parks them at GET /api/social-outreach/queue for your review. You approve or reject each draft via POST /approve/<event_id> before it posts. This gives you the research and drafting speed of the agent while keeping a human in the loop on every outbound message — useful when entering a new community where you want to calibrate tone first.
Generic social automation tools blast canned messages on a schedule regardless of context. Guaardvark's outreach loop reads the actual thread content, checks subreddit rules before engaging, self-grades every draft before posting, and enforces hard rate limits that prevent the kind of volume that triggers shadow-bans. The entire pipeline runs on your own machine, so there is no third-party service holding your credentials or posting history. The kill switch is a single API call. The audit log is yours — a plain JSONL file you can inspect, export, or delete at any time. The goal is sustainable organic engagement, not carpet-bombing.
Yes — Social Outreach is available in v2.6, released today. Install Guaardvark to start using it, or star the GitHub repo to follow ongoing development.
The design prioritises account safety. Hard caps of one post per 30 minutes per platform and eight posts per 24 hours are enforced in Redis — well below Reddit's documented limits. The agent checks subreddit rules for no-self-promo clauses and aborts if found. Relevance filtering means the agent only engages in threads where the comment is genuinely on-topic. That said, you run this on your own account at your own risk, and you should review the audit log regularly to catch any edge cases in the quality grader.
Edit data/agent/social_outreach_targets.json, which contains a reddit.outreach_subs array. Add subreddit names (without the r/ prefix). The file is created with empty arrays on first startup; populate it before enabling the loop. Discord channels are configured in plugins/discord/config.yaml under the outreach.channels key.
The default threshold is 0.7 on a 0–1 scale returned by the LLM's self-assessment. Drafts below this are logged as drafted with status rejected but never posted. You can adjust the threshold via the social_outreach_grade_threshold setting in Settings → System. Raising it to 0.85 makes the agent more conservative; lowering it accepts more borderline drafts.
Yes. Set social_outreach_supervised=true in Settings. In supervised mode, every draft that passes the quality grade lands in the approval queue at GET /api/social-outreach/queue rather than posting automatically. Approve via POST /approve/<event_id> or reject via POST /reject/<event_id>. The Guaardvark dashboard will surface a pending-approvals count when the queue is non-empty.