socai
A local research agent that actually reads social media: it drives your signed-in Chrome like a researcher would — searching, reading posts and comments, and returning structured results.
- Source repo
- socai-io/socai
- Stars
- ★ 217
- Last updated
- 1d ago
- License
- Apache-2.0
- Primary language
- Rust
- FA score
- 65/100 · Some gaps
At a glance
- Works with
- Portable with changesCodex · Claude Code
- You'll need
- Typical use
- A market researcher comparing how sugar-free tea is discussed on RedNote, Douyin, and Instagram, citing specific posts, comments, and replies.
- Main limitation
- Depends on local Chrome and per-platform login state, so it cannot run unattended and your accounts bear platform risk-control pressure.
- Source review
- 65/100 · Some gaps
What does this agent do, and when should you use it?
socai is a local social-media research agent that is neither a scraper nor a reverse-engineered API: it drives your signed-in Chrome over CDP, opens real pages, and reads posts, comments, and author profiles across Xiaohongshu, Douyin/TikTok, Instagram, and LinkedIn, with local OCR on images and speech transcription on videos. It ships three interfaces sharing the same browser connection and run-record core: a desktop app (macOS/Windows), a structured CLI designed for agents like Claude Code and Codex, and an interactive terminal UI (running socai with no subcommand). Every run writes structured JSON, media artifacts, a media_manifest., and reports or spreadsheets under ~/.socai/runs/<timestamp>_<task>/. Research commands are read-only by default; publish and comment commands require an explicit target and content and never automatically retry uncertain submissions. The project is Apache-2.0 licensed, and the hosted cloud browser (socai pro remote mode) is currently in beta.
socai connects to your Chrome (via remote debugging) and runs per-platform research commands: socai xhs search supports --num-notes, --num-comments, --filter publish_time=一周内, --download-media, --ocr, and --transcribe-audio; socai dy, socai tiktok, socai instagram, and socai linkedin provide search, author profiles, post details, comments, and media downloads. OCR runs locally on images, and transcription uses a local Whisper helper installed alongside socai (cargo install --path asr). Running socai without a subcommand opens the terminal interface for agent-led cross-platform research. Results are written to ~/.socai/runs/ including structured JSON, media_manifest., and debug snapshots. socai config set chrome.profile switches among four browser modes: existing, managed, auto, and remote. Write operations are limited to explicit invocations such as socai xhs comment '<complete_note_url>' --text 'Exact comment text'.
- A market researcher comparing how sugar-free tea is discussed on RedNote, Douyin, and Instagram, citing specific posts, comments, and replies.
- A Claude Code or Codex user pulling structured JSON social data through CLI subcommands inside scripted workflows.
- A content team reading competitor author profiles (socai xhs author <author_id>) to analyze their notes and comment engagement.
- An analyst who needs text from video content: --ocr for cover text and --transcribe-audio with the local Whisper helper for speech.
- A user exporting findings as reports, spreadsheets, or Feishu documents; the desktop app supports preview, download, and Feishu export.
How do you install or deploy this agent?
Desktop app: download the macOS universal .dmg or Windows x86_64 setup.exe from GitHub Releases, then follow the in-app steps to connect Chrome (first connection requires enabling remote debugging and confirming the browser permission prompt).
CLI install (macOS):
bash
curl -fsSL https://github.com/socai-io/socai/releases/latest/download/install.sh | shCLI install (Windows PowerShell):
powershell
$installer = Join-Path $env:TEMP 'socai-install.ps1'; Invoke-WebRequest -UseBasicParsing https://github.com/socai-io/socai/releases/latest/download/install.ps1 -OutFile $installer; Unblock-File $installer; & $installerThe installers place socai at ~/.socai/bin/socai (macOS) or %USERPROFILE%\.socai\bin\socai.exe (Windows) and configure the PATH. If no prebuilt binary exists, or for development:
bash
git clone https://github.com/socai-io/socai.git
cd socai
cargo install --path cli --force --locked
cargo install --path asr --force --lockedHow do you use this agent?
Connect Chrome, then run structured commands. Examples:
bash
socai xhs search "beginner camping gear mistakes" --num-notes 10 --num-comments 8 --pretty
socai dy search "beginner camping gear" --num 20
socai tiktok search "beginner camping gear" --num 20 --pretty
socai instagram search "beginner camping gear" --num 20 --pretty
socai linkedin search "product designer" --type people --num 20 --prettyRedNote search also supports platform filters and media processing:
bash
socai xhs search "content marketing ideas" \
--num-notes 30 \
--num-comments 20 \--filter publish_time=一周内 \
--filter sort=最多评论 \
--download-media \
--ocr \
--prettyRun socai with no subcommand to open the terminal interface and let the agent run natural-language cross-platform tasks. Switch browser modes with:
bash
socai config set chrome.profile managed
socai stopWhat are this agent's strengths and limitations?
- Works through your real signed-in Chrome pages, avoiding public API limits and scraper bans.
- Reads deeper than search cards: opens posts, expands comments and replies, reads author profiles, and runs local OCR and Whisper transcription.
- Five platforms (RedNote, Douyin, TikTok, Instagram, LinkedIn) share one CLI, desktop app, and run-record core, with a media_manifest. inventory per run.
- Research commands are read-only by default; writes need explicit target and content, verify the signed-in actor before dispatch, and never auto-retry — a clear safety boundary.
- Depends on local Chrome and per-platform login state, so it cannot run unattended and your accounts bear platform risk-control pressure.
- Desktop builds are macOS and Windows only — no Linux build; the hosted cloud browser (remote mode) is beta and requires socai pro activation.
- Transcription requires building and installing a separate local Whisper helper (the asr crate) via Cargo — extra cost for non-Rust users.
- Video transcription on some routes requires signing in and selecting the socai agent; the bundled model applies only on paid or offline transcription routes.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| socai This agent | 65 · Some gaps | — | ★ 217 | 1d ago | Rust | Codex · Claude Code |
| Jev Social | 71 · Some gaps | CLIFree + model costs | ★ 89 | 1d ago | JavaScript | — |
| Social Media Research Skills Pack | 27 · Major gaps | Agent plugin / skillFree + model costs | ★ 2.9k | 1mo ago | Python | ChatGPT · Codex · Claude Code |
| EvoScientist: Self-Evolving AI Scientist | 51 · Major gaps | CLIFree + model costs | ★ 5k | 1d ago | Python | OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
Write commands default off, require explicit targets, and use one-time receipts against auto-resend — supports user_confirmation and external_effects at 2. But least_privilege is only 1: the tool takes over the user's logged-in Chrome via remote debugging, a very high-privilege default with managed/remote profiles merely optional. Sensitive_data_handling is 1: it rides on the user's session cookies/credentials with no stated encryption, redaction, or isolation. Rollback is 1: only `socai stop` and config toggles; no undo path for writes or downloads is described.
README is internally consistent (modes, config paths, commands, platform table all agree) and multiple install paths (dmg/exe/scripts/cargo) aid availability — 2 each. Failure messaging is only evidenced by mentions of --help diagnostic commands; no error semantics, exit codes, or retry policy documented — 1.
Three distinct audiences (desktop users, CLI/scripts, agent integrations), a full platform matrix, and exact filter values justify 3 for audience_and_scenarios. Capability boundaries only 2: read-only default and pro beta limits are stated, but platform-ToS/anti-bot risk is barely addressed. Environment fit 2: macOS/Windows only, Windows installer x86_64-only, no Linux desktop build.
Clear information architecture (multilingual READMEs, DEVELOPMENT.md, site extension guide), thorough install notes across three paths, stable subcommand naming, and a complete Apache-2.0 LICENSE earn 3s. Known_limitations is 1: aside from pro session limits, no known issues, ban risks, or fragile-selector caveats. Versioning_changelog is 1: workspace version 0.6.1 but no changelog visible. Maintenance_responsibility 2: CI workflows show active maintenance, but no maintainer list, security policy, or response commitment.
Output usability is strong: structured JSON, per-run directories under ~/.socai/runs, media_manifest., report/table preview — 3. Marginal value 2: driving a real logged-in browser is genuinely differentiated but predicated on platforms tolerating it. Cost_benefit 1: user-facing costs (LLM usage, account-ban risk) are unquantified; only CI mentions ~¥4 per benchmark run.
Claims are partially traceable to concrete commands and config paths — 2. Cross-source corroboration is 1: only a README translation, Cargo.toml, and workflows are in scope; core claims (receipt mechanism, OCR, Whisper helper) have no code or test evidence here to check. Facts and inference are mostly separated — 2 — though marketing phrasing ('Fast. Precise. Deep.') is unquantified.
- The default mode attaches to your logged-in Chrome via remote debugging, effectively granting read access to all your sessions; prefer the managed profile and a dedicated account.
- Automated access to XHS/Douyin/TikTok/Instagram/LinkedIn may violate platform terms of service and risk account restriction — barely mentioned in the docs.
- Publisher identity is unverified and the install uses curl | sh; review the script before executing.
- Write operations (posting/comments) claim receipt-based confirmation, but the implementation is unverifiable in this static review — manually review before any write in sensitive contexts.
- No changelog or known-issues document; read release notes before upgrading and keep a rollback path.