social-agent-cli 4.4.0 → 5.0.0

package/README.md

@@ -1,225 +1,94 @@
 # social-agent-cli
 
-AI-powered social media automation tool with self-healing browser automation. Teach it any action on any platform — it learns, adapts, and recovers from errors automatically.
-
-## How It Works
-
-```
-You: "like this tweet and retweet it: https://x.com/..."
-
-  1. [Planner]   → Parses natural language command
-  2. [Knowledge] → Loads platform-specific knowledge (URLs, selectors, limits)
-  3. [Map Check] → Checks learned action maps
-  4. [Learn]     → If missing, opens Chrome, takes screenshot + DOM, AI creates selector map
-  5. [Runner]    → Executes steps sequentially
-  6. [Heal]      → On failure: screenshots page, AI re-plans remaining steps (effort escalates)
-```
-
-## Features
-
-- **Natural language commands** — `social-agent run x "like and retweet this tweet"`
-- **Self-healing** — When selectors break, AI sees the screen and re-plans from where it left off
-- **Learning** — Teach any action once, reuse forever. Maps are saved as JSON
-- **Combination** — Chains multiple learned actions in a single command
-- **Real Chrome profile** — Uses your actual Chrome profile via CDP. No bot detection
-- **Zero hardcode** — No platform-specific selectors in code. Everything is AI-learned
-- **Free API drivers** — Mastodon, Bluesky, Telegram via direct API (no browser needed)
-- **Browser automation** — X, LinkedIn, Instagram, Facebook via Chrome
-- **Post history** — Logs every action. AI matches your tone in future posts
-- **Git hook** — Notifies you after `git push` to suggest social media posts
-- **Claude Code integration** — `claude-social` mode + `/social` slash command
+Social media automation that works like an API. Post to X and LinkedIn from the terminal or Claude Code.
 
 ## Install
 
 ```bash
 npm install -g social-agent-cli
+npm install -g agent-browser && agent-browser install
 social-agent setup
 ```
 
-The setup wizard asks your name, social handles, API tokens, and configures everything — Chrome profile selection, git hooks, shell aliases.
-
-## Quick Start
+## Post
 
 ```bash
-# 1. First-time setup
-social-agent setup
+# Text post
+social-agent run x --content "Hello world"
+social-agent run linkedin --content "Hello world"
 
-# 2. Login to browser platforms (one-time)
-social-agent login x
-social-agent login linkedin
+# 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
 
-# 3. Teach actions
-social-agent learn x                                    # learn to post (default)
-social-agent learn "learn to like tweets" x             # learn liking
-social-agent learn "learn to send connection request" linkedin
-
-# 4. Use with natural language
-social-agent run x "like this tweet: https://x.com/user/status/123"
-social-agent run x "like and retweet: https://x.com/user/status/123"
-social-agent run linkedin "send connection requests to 3 people"
-social-agent post "New feature released!" --platforms mastodon,bluesky
+# Mastodon (API)
+social-agent post "Hello" --platforms mastodon --image /path/to/image.jpg
 ```
 
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `social-agent setup` | First-time setup wizard |
-| `social-agent login <platform>` | Select Chrome profile and verify login |
-| `social-agent learn "<task>" <platform>` | AI learns a new action from the page |
-| `social-agent run <platform> "<command>"` | Execute with natural language |
-| `social-agent post "<text>" --platforms x,mastodon` | Post to platforms |
-| `social-agent status` | Show connected platforms |
-| `social-agent history` | Show action history |
-
-## Supported Platforms
-
-### API-based (free, no browser needed)
-| Platform | Auth | Features |
-|----------|------|----------|
-| **Mastodon** | Access token | Post, media upload, like, boost, follow |
-| **Bluesky** | App password | Post, media, like, repost, follow |
-| **Telegram** | Bot token | Send messages, photos, videos to channels |
-
-### Browser-based (Chrome automation)
-| Platform | Method | Notes |
-|----------|--------|-------|
-| **X (Twitter)** | CDP + real Chrome | Free tier friendly, no API costs |
-| **LinkedIn** | CDP + real Chrome | Connection requests, posts, reactions |
-| **Instagram** | CDP + real Chrome | Aggressive anti-bot, use with caution |
-| **Facebook** | CDP + real Chrome | Checkpoint system, careful usage |
-
-## Self-Healing
-
-When a step fails, AI doesn't just retry — it **sees the screen and re-plans**:
+## How It Works
 
 ```
-Step 6: Click "Post" button ✗
-  [heal] AI analyzing screen (effort: low)...
-  → "Post button is inside a scrollable container, need to scroll first"
-  → New plan: scroll down + click with updated selector
-
-Step 6 (new): Scroll down ✓
-Step 7 (new): Click post button ✓
+1. Cached CSS selector (instant)
+       ↓ broken?
+2. ARIA snapshot + ref match (ms)
+       ↓ not found?
+3. Claude AI finds the right element (5-15s)
 ```
 
-Effort escalates on repeated failures: `low → medium → medium`
-
-## Selector Maps
-
-Learned actions are saved as JSON in `~/.social-agent/maps/`:
-
-```json
-{
-  "platform": "x",
-  "action": "like_tweet",
-  "parameters": ["{{TWEET_URL}}"],
-  "steps": [
-    { "action": "goto", "url": "{{TWEET_URL}}" },
-    { "action": "wait", "waitMs": 2000 },
-    { "action": "click", "selector": "[data-testid='like']",
-      "fallbackSelectors": ["[aria-label*='Like']"] },
-    { "action": "wait", "waitMs": 1000 }
-  ]
-}
-```
+Uses [agent-browser](https://github.com/vercel-labs/agent-browser) (Rust) for fast browser automation via CDP, connected to your real Chrome profile. No bot detection.
 
-## Chrome Integration
+## Claude Code Integration
 
-- **CDP (Chrome DevTools Protocol)** connection
-- Chrome open → connects to existing instance, opens new tab
-- Chrome closed → launches with your selected profile
-- Only closes the tab, **never kills Chrome**
-- `navigator.webdriver = false` to avoid detection
-- `--enable-automation` flag removed
+```
+/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)
+```
 
-## Claude Code Integration
+When suggestions are on, Claude notices milestones in your work and asks: "This is worth sharing. Want to create a post?"
 
-### `claude-social` mode
-Run Claude with social media awareness. It suggests posts at milestones:
+## Setup
 
 ```bash
-claude-social
-
-# While working...
-# AI: "This feature is worth sharing. Type /social to create a post."
+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
 ```
 
-### `/social` slash command
-Creates a post from your current work context:
-1. Analyzes conversation history + git log + project info
-2. Reads post history for tone matching
-3. Asks which platforms
-4. Generates platform-optimized content
-5. Creates image (optional, platform-sized)
-6. Posts in background after approval
-
-## Data Directory
-
-Everything lives in `~/.social-agent/`:
+## Architecture
 
 ```
 ~/.social-agent/
-├── config.json              # API keys and settings
-├── social-mode-prompt.md    # AI assistant personality (editable)
-├── profile-map.json         # Platform → Chrome profile mapping
-├── history.json             # Action log
-├── knowledge/               # Platform knowledge files
-│   ├── x.md                 # X/Twitter: selectors, URLs, limits
-│   ├── linkedin.md          # LinkedIn: aria-labels, anti-bot
-│   ├── instagram.md         # Instagram: aggressive anti-bot docs
-│   ├── facebook.md          # Facebook: checkpoint system
-│   ├── mastodon.md          # Mastodon: full API reference
-│   ├── bluesky.md           # Bluesky: AT Protocol API
-│   └── telegram.md          # Telegram: Bot API
-├── maps/                    # Learned action maps (JSON)
-├── profiles/                # Chrome CDP working directory
-└── screenshots/             # AI analysis screenshots
+├── 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
 ```
 
-## Adding New Platforms
-
-No code changes needed:
-
-1. Add URL to `BROWSER_PLATFORMS` in `cli.ts`
-2. Create `knowledge/platform.md`
-3. `social-agent login platform`
-4. `social-agent learn platform`
-5. `social-agent run platform "do something"`
-
-## Architecture
+## Supported Platforms
 
-```
-social-agent/
-├── bin/social-agent.js         # Global CLI entry point
-├── cli.ts                      # Command router
-├── install.ts                  # Setup wizard
-├── core/
-│   ├── config.ts               # Config & paths (~/.social-agent/)
-│   ├── types.ts                # TypeScript interfaces
-│   ├── profiles.ts             # Chrome profile discovery & selection
-│   ├── history.ts              # Action logging
-│   └── screenshot.ts           # HTML → JPEG converter
-├── ai/
-│   ├── mapper.ts               # Claude -p: create/heal selector maps
-│   ├── planner.ts              # Natural language → execution plan
-│   ├── runner.ts               # Execute plan with heal-on-failure
-│   └── knowledge.ts            # Platform knowledge reader
-├── platforms/
-│   ├── mastodon.ts             # Mastodon API driver
-│   ├── bluesky.ts              # Bluesky AT Protocol driver
-│   └── browser/
-│       └── driver.ts           # Playwright + Chrome CDP + anti-detection
-├── knowledge/                  # Platform knowledge (7 platforms, 7000+ lines)
-└── hooks/
-    └── post-push               # Git hook for post suggestions
-```
+| Platform | Method | Text | Image |
+|----------|--------|------|-------|
+| X | Browser (CDP) | ✓ | ✓ |
+| LinkedIn | Browser (CDP) | ✓ | ✓ |
+| Mastodon | API | ✓ | ✓ |
 
 ## Requirements
 
 - Node.js 18+
-- Google Chrome (macOS — Linux/Windows support planned)
-- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) (`npm install -g @anthropic-ai/claude-code`)
+- Google Chrome (macOS)
+- [agent-browser](https://github.com/vercel-labs/agent-browser)
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (for /social commands)
 
 ## License
 

package/bin/social-agent.js

@@ -106,24 +106,20 @@ switch (command) {
   Setup:
     social-agent setup                    First-time setup
     social-agent login <platform>         Chrome profile select (x, linkedin)
-    social-agent config                   Show config file paths
+    social-agent config                   Show config paths
 
   Post:
-    social-agent run x "post this: Hello world"
-    social-agent run x "post with image: msg, image: /path/to/img.jpg"
-    social-agent run linkedin "share this post: Hello"
-    social-agent post "text" --platforms mastodon
-
-  Actions:
-    social-agent run x "like this: https://x.com/..."
-    social-agent run x "like and retweet: https://x.com/..."
+    social-agent run x --content "Hello world"
+    social-agent run x --content "Hello" --image /path/to/img.jpg
+    social-agent run linkedin --content "Hello"
+    social-agent run linkedin --content "Hello" --image /path/to/img.jpg
+    social-agent post "text" --platforms mastodon --image /path/to/img.jpg
 
   Info:
     social-agent status                   Connected platforms
     social-agent history                  Action log
 
   Claude Code:
-    claude-social                         Social-aware mode
     /social                               Create post from work context
     /social-suggest on|off                Toggle suggestions
     /social-suggest-level 0-5             Sensitivity (0=off, 3=balanced)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "social-agent-cli",
-  "version": "4.4.0",
+  "version": "5.0.0",
   "description": "AI-powered social media agent - free APIs + browser automation with self-healing selectors",
   "type": "module",
   "bin": {