social-agent-cli

Social media automation that works like an API. Post to X and LinkedIn from the terminal or Claude Code.

Install

npm install -g social-agent-cli
npm install -g agent-browser && agent-browser install
social-agent setup

Post

# Text post
social-agent run x --content "Hello world"
social-agent run linkedin --content "Hello world"

# With image
social-agent run x --content "Check this out" --image /path/to/image.jpg
social-agent run linkedin --content "New project" --image /path/to/image.jpg

# Mastodon (API)
social-agent post "Hello" --platforms mastodon --image /path/to/image.jpg

How It Works

1. Cached CSS selector (instant)
       ↓ broken?
2. ARIA snapshot + ref match (ms)
       ↓ not found?
3. Claude AI finds the right element (5-15s)

Uses agent-browser (Rust) for fast browser automation via CDP, connected to your real Chrome profile. No bot detection.

Claude Code Integration

/social                    Create post from current work context
/social-suggest on         Enable post suggestions at milestones
/social-suggest off        Disable suggestions
/social-suggest-level 3    Set sensitivity (0=off, 5=max)

When suggestions are on, Claude notices milestones in your work and asks: "This is worth sharing. Want to create a post?"

Setup

social-agent setup          # Name, language, style, platform logins
social-agent login x        # Select Chrome profile for X
social-agent login linkedin # Select Chrome profile for LinkedIn
social-agent status         # Show connected platforms
social-agent config         # Show config file paths
social-agent history        # Show post history

Architecture

~/.social-agent/
├── config.json              # API keys (Mastodon)
├── social-mode-prompt.md    # AI personality (editable)
├── profile-map.json         # Platform → Chrome profile
├── history.json             # Post log
├── maps/
│   ├── x.json               # X post steps + cached selectors
│   └── linkedin.json        # LinkedIn post steps + cached selectors
├── knowledge/               # Platform knowledge (X, LinkedIn, Mastodon)
├── profiles/chrome-cdp/     # Chrome CDP session data
└── screenshots/             # Debug screenshots

Supported Platforms

| Platform | Method | Text | Image | |----------|--------|------|-------| | X | Browser (CDP) | ✓ | ✓ | | LinkedIn | Browser (CDP) | ✓ | ✓ | | Mastodon | API | ✓ | ✓ |

Requirements

• Node.js 18+
• Google Chrome (macOS)
• agent-browser
• Claude Code (for /social commands)

License

MIT