social-duo

A production-quality Python CLI where two AI agents collaborate to draft, critique, revise, and reply to social media content. The tool maintains a local workspace with config, history, and exports.

Highlights

• Two agents: Writer and Editor/Responder
• Iterative loop with PASS/FAIL gating
• Platform constraints and brand voice
• SQLite history with export
• JSON and rich CLI output

Install (NPM-first)

Global install (recommended for day-to-day CLI use):

npm i -g social-duo

Then run either command name:

social-duo --help
social_duo --help

No virtualenv activation is required in each new terminal. The wrapper manages a Python venv at ~/.social-duo/venv.

Install (Python dev)

cd social-duo
python -m venv .venv
source .venv/bin/activate
pip install -e .

Or with pipx:

pipx install -e .

Setup

cp .env.example .env
export OPENAI_API_KEY=your_key_here
# Optional
export OPENAI_BASE_URL=https://api.openai.com/v1
export OPENAI_MODEL=gpt-4o-mini

Initialize the workspace:

social-duo init

Examples

LinkedIn post about agentic workflows:

social-duo post --platform linkedin --goal educate --topic "agentic workflows" --audience "engineering leaders" --tone "confident" --length medium

X thread of 5 tweets about vector databases for semantic search:

social-duo post --platform x --thread 5 --goal educate --topic "vector databases for semantic search" --audience "ML engineers" --tone technical --length short

Replies to a critical comment (polite + direct):

social-duo reply --text "This feels like vaporware." --platform x --style polite --stance neutral
social-duo reply --text "This feels like vaporware." --platform x --style direct --stance disagree

Autonomous discuss mode (no topic provided):

social-duo discuss --platform x --turns 10 --verbose

MOLTBOOK-LITE simulation:

social-duo molt run --turns 25
social-duo molt watch --run-id <id>
social-duo molt export --run-id <id> --format md

Resume session via history and chat:

social-duo history --list
social-duo history --show 3
social-duo chat --session 3

Commands

• social-duo init
• social-duo post
• social-duo reply
• social-duo discuss
• social-duo molt
• social-duo chat
• social-duo history
• social-duo config

social_duo is also available as an alias when installed through npm.

Troubleshooting

• Missing key: set OPENAI_API_KEY in your environment.
• Base URL errors: set OPENAI_BASE_URL (default is https://api.openai.com/v1).
• Model errors: set OPENAI_MODEL to a valid chat model name for your provider.

Notes

• All artifacts are stored in .social-duo/ in the current directory.
• Use --json for machine-readable output.
• Use --verbose to see full agent exchanges.

NPM Wrapper

The npm package installs the Python CLI from GitHub:

npm i -g social-duo
social-duo --help

This uses the GitHub repo as the install source and creates a venv under ~/.social-duo/venv.