Magpie

Magpie by Circuit Forge LLC — cross-product community signal gathering and social media management tool (internal, MIT).

Magpie watches Reddit and Lemmy communities for signals relevant to CircuitForge products, surfaces engagement opportunities for human review, and (once approved) posts comments, submissions, and blog announcements on a schedule. It also tracks post performance over time.

Stack

• Backend: FastAPI + SQLite (app/), APScheduler for scheduled jobs
• Frontend: Vue 3 SPA (frontend/), deployed at /magpie/ sub-path via a custom static server with API reverse proxy (scripts/spa_server.py)
• Posting: Playwright-driven Reddit sessions (Reddit's API access is effectively defunct for this use case) + Lemmy's native HTTP API
• MCP server: mcp/server.js — stdio MCP server exposing campaign, signal, opportunity, and Reddit/Lemmy session tools to Claude Code

Core concepts

• Campaigns — a target (subreddit/community) + content variants + schedule
• Signals — posts/comments pulled from watched communities (Signal Queue)
• Opportunities — signals flagged as worth engaging with; require human approval before Magpie posts anything (approve/dismiss workflow)
• Sub rules — per-community posting rules and flair requirements, scraped and classified so campaigns don't violate community guidelines
• Platforms — pluggable posting strategies (app/services/platforms/): Reddit comment, Reddit post, blog post (via Directus), Lemmy/PieFed comment (JWT-authenticated). Discovery (POST /subs/discover) additionally covers Mastodon (hashtag search) and Bluesky (custom feed search), read-only — posting to those two is not yet implemented

Running it

./manage.sh start          # API (:8532) + frontend dev server (:8531)
./manage.sh status         # process status, scheduler jobs, Reddit session age
./manage.sh logs           # tail all logs
./manage.sh login          # refresh Reddit Playwright session
./manage.sh build          # build frontend for menagerie deploy (/magpie/ base path)
./manage.sh serve          # serve pre-built dist on :8531
./manage.sh open           # open dashboard in browser

Full command list: ./manage.sh with no arguments.

Multiple instances (per-collaborator carve-outs)

API_PORT/WEB_PORT/DATA_DIR (and BASE_PATH/DIST_DIR for build/serve) are overridable via MAGPIE_API_PORT, MAGPIE_WEB_PORT, MAGPIE_DATA_DIR, MAGPIE_BASE_PATH, MAGPIE_DIST_DIR — lets a second fully-isolated instance (separate DB, separate sessions/ dir, separate frontend build) run alongside the primary one. Used for Daniel's (nimdah) carve-out at /magpie-nimdah — see circuitforge-plans/magpie/superpowers/specs/2026-08-13-multi-tenant-staging-design.md for the full design (including the API-key auth path mcp/server.js uses for MCP clients that have no browser session cookie to authenticate with).

Copy .env.example to .env and fill in Reddit credentials, Chrome binary path, and (if using Lemmy comment posting) LEMMY_INSTANCE/LEMMY_USERNAME/ LEMMY_PASSWORD before first run.

Status

Internal tool — active development. Reddit and Lemmy comment/post/discovery pipelines, Mastodon/Bluesky discovery, blog post publishing, session refresh UI, and sub-path deployment are live. Open backlog items are tracked as Forgejo issues (Mastodon/Bluesky posting, LinkedIn discovery, AI-drafted opportunity responses, per-sub content variant templates, shared memory/knowledge-graph integration).

See /Library/Development/CircuitForge/CLAUDE.md for CircuitForge-wide conventions and repo layout.