Skip to content
Back to search

x-social-skill

MarketplaceWorks with Claude CodeGitHub

X (Twitter) browser automation via Playwright + Chrome

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/baijunjie--x-social-skill/badge.svg)](/listings/baijunjie--x-social-skill)

HTML

<a href="/listings/baijunjie--x-social-skill"><img src="/api/listings/baijunjie--x-social-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- **Node.js** >= 20 (with npm) - **Google Chrome** installed

1. Install the Plugin

The plugin carries only an installer, which the model cannot invoke on its own, so installing the plugin exposes nothing to agents yet.

Claude Code:

claude plugin marketplace add baijunjie/x-social-skill
claude plugin install x-social@x-social-skill
# restart Claude Code

Codex:

codex plugin marketplace add baijunjie/x-social-skill
codex plugin add x-social@x-social-skill
# start a new session

Install from GitHub rather than a local path: a local marketplace points straight at that directory, and moving or deleting it breaks the skill.

2. Install into a Project

In the project that should get X automation, run the installer:

- Claude Code: `/x-social:install` — installs to `.claude/skills/x-social/` - Codex: `$x-social:install` — installs to `.agents/skills/x-social/`

Commit the installed directory; it carries its own `.gitignore` for `node_modules/`. Then restart Claude Code / start a new Codex session. Only agents in this project see the `x-social` skill.

npm dependencies are installed into the skill directory by `run.sh` on its first run, so nothing else needs installing.

To update: refresh the plugin (`claude plugin marketplace update x-social-skill && claude plugin update x-social@x-social-skill`; Codex: `codex plugin marketplace upgrade x-social-skill && codex plugin add x-social@x-social-skill`), then run the installer again in each project. It reports "up to date" when nothing changed, and lists the files it would overwrite before replacing hand edits.

3. Configure Chrome Path

Chrome is expected at `/Applications/Google Chrome.app/Contents/MacOS/Google Chrome` by default.

If Chrome is installed elsewhere, find it and add it to `~/.x-social-skill/.env`:

# Find Chrome installation (macOS)
CHROME=$(mdfind "kMDItemCFBundleIdentifier == 'com.google.Chrome'" 2>/dev/null | head -1)

# If found, write to .env
if [ -n "$CHROME" ]; then
  mkdir -p ~/.x-social-skill
  echo "CHROME_PATH=$CHROME/Contents/MacOS/Google Chrome" >> ~/.x-social-skill/.env
  echo "Added CHROME_PATH to ~/.x-social-skill/.env"
else
  echo "Chrome not found. Please install Google Chrome first."
fi

4. Authenticate with X

Ask the agent to set up X, or run the setup script yourself from the installed skill directory:

./run.sh setup

This opens Chrome on a fresh profile for you to log in to X manually. The script auto-detects login completion (timeout: 5 minutes), reads the account's handle and saves the session under `.x-social/accounts/<handle>/` at the project root — accounts belong to the project the agent is working in. Run it outside a git project, or with `X_SOCIAL_HOME=~/.x-social-skill`, to set up user-level accounts shared by all projects.

Run it again with another account to add it. Once several accounts are set up, choose one with `X_ACCOUNT` — scripts refuse to guess.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 20 lines
  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "x-social-skill",
  4. "description": "X (Twitter) browser automation via Playwright + Chrome",
  5. "owner": {
  6. "name": "BaiJunjie",
  7. "email": "bjj19851010@gmail.com"
  8. },
  9. "plugins": [
  10. {
  11. "name": "x-social",
  12. "description": "Installer that adds X (Twitter) automation to a single project: post, like, reply, retweet, quote, search, list mentions and delete your own tweets through your own Chrome, with multiple accounts",
  13. "author": {
  14. "name": "BaiJunjie"
  15. },
  16. "source": "./",
  17. "category": "productivity"
  18. }
  19. ]
  20. }
README.md · README · 236 lines
  1. **English** | [中文](README.zh-CN.md)
  2. # x-social-skill
  3. X (Twitter) browser automation skill — post, like, reply, retweet, quote, search, list mentions and delete your own tweets via Playwright + Chrome. Ships as a plugin for Claude Code and Codex that installs the skill into the projects you choose — agents in other projects never see it — with multiple accounts per project.
  4. ## Why Browser Automation?
  5. - **API is expensive** — X official API requires a paid subscription ($200+/month) for posting
  6. - **Real browser fingerprint** — Reuses the user's actual Chrome, not a bundled Chromium, so the automation fingerprints X looks for are absent
  7. - **One-time login** — Log in manually once per account, session persists in a Chrome profile
  8. - **Headless when it has to be** — Optional, with the `HeadlessChrome` user agent and client hints masked; see [Headless](#headless)
  9. ## Features
  10. | Action | Script (in the installed skill directory) | Description |
  11. |--------|--------|-------------|
  12. | Post | `scripts/post.ts` | Publish tweets with text and/or images (up to 4) |
  13. | Like | `scripts/like.ts` | Like any tweet |
  14. | Reply | `scripts/reply.ts` | Reply to tweets, optionally with images |
  15. | Retweet | `scripts/retweet.ts` | Retweet without comment |
  16. | Quote | `scripts/quote.ts` | Quote tweet with comment, optionally with images |
  17. | Search | `scripts/search.ts` | Search the "Latest" tab, returning structured tweets with author, text, timestamp and counts |
  18. | List own | `scripts/my-tweets.ts` | Enumerate the signed-in account's own tweets from the profile timeline |
  19. | Mentions | `scripts/mentions.ts` | List replies and @-mentions addressed to the signed-in account, from the notifications Mentions tab |
  20. | Delete | `scripts/delete.ts` | Delete one tweet or a batch by URL |
  21. | Purge | `scripts/purge.ts` | Bulk delete own tweets straight from the timeline, optionally filtered by a regex |
  22. **Deleting is permanent — X offers no undo.** `purge.ts` without a `match` filter deletes every own tweet the timeline serves, up to `limit`.
  23. All scripts use stdin/stdout JSON — pipe input in, parse output out. See [SKILL.md](skills/install/template/x-social/SKILL.template.md) for the full IO protocol.
  24. ## Getting Started
  25. ### Prerequisites
  26. - **Node.js** >= 20 (with npm)
  27. - **Google Chrome** installed
  28. ### 1. Install the Plugin
  29. The plugin carries only an installer, which the model cannot invoke on its own, so installing the plugin exposes nothing to agents yet.
  30. Claude Code:
  31. ```bash
  32. claude plugin marketplace add baijunjie/x-social-skill
  33. claude plugin install x-social@x-social-skill
  34. # restart Claude Code
  35. ```
  36. Codex:
  37. ```bash
  38. codex plugin marketplace add baijunjie/x-social-skill
  39. codex plugin add x-social@x-social-skill
  40. # start a new session
  41. ```
  42. Install from GitHub rather than a local path: a local marketplace points straight at that directory, and moving or deleting it breaks the skill.
  43. ### 2. Install into a Project
  44. In the project that should get X automation, run the installer:
  45. - Claude Code: `/x-social:install` — installs to `.claude/skills/x-social/`
  46. - Codex: `$x-social:install` — installs to `.agents/skills/x-social/`
  47. Commit the installed directory; it carries its own `.gitignore` for `node_modules/`. Then restart Claude Code / start a new Codex session. Only agents in this project see the `x-social` skill.
  48. npm dependencies are installed into the skill directory by `run.sh` on its first run, so nothing else needs installing.
  49. To update: refresh the plugin (`claude plugin marketplace update x-social-skill && claude plugin update x-social@x-social-skill`; Codex: `codex plugin marketplace upgrade x-social-skill && codex plugin add x-social@x-social-skill`), then run the installer again in each project. It reports "up to date" when nothing changed, and lists the files it would overwrite before replacing hand edits.
  50. ### 3. Configure Chrome Path
  51. Chrome is expected at `/Applications/Google Chrome.app/Contents/MacOS/Google Chrome` by default.
  52. If Chrome is installed elsewhere, find it and add it to `~/.x-social-skill/.env`:
  53. ```bash
  54. # Find Chrome installation (macOS)
  55. CHROME=$(mdfind "kMDItemCFBundleIdentifier == 'com.google.Chrome'" 2>/dev/null | head -1)
  56. # If found, write to .env
  57. if [ -n "$CHROME" ]; then
  58. mkdir -p ~/.x-social-skill
  59. echo "CHROME_PATH=$CHROME/Contents/MacOS/Google Chrome" >> ~/.x-social-skill/.env
  60. echo "Added CHROME_PATH to ~/.x-social-skill/.env"
  61. else
  62. echo "Chrome not found. Please install Google Chrome first."
  63. fi
  64. ```
  65. ### 4. Authenticate with X
  66. Ask the agent to set up X, or run the setup script yourself from the installed skill directory:
  67. ```bash
  68. ./run.sh setup
  69. ```
  70. This opens Chrome on a fresh profile for you to log in to X manually. The script auto-detects login completion (timeout: 5 minutes), reads the account's handle and saves the session under `.x-social/accounts/<handle>/` at the project root — accounts belong to the project the agent is working in. Run it outside a git project, or with `X_SOCIAL_HOME=~/.x-social-skill`, to set up user-level accounts shared by all projects.
  71. Run it again with another account to add it. Once several accounts are set up, choose one with `X_ACCOUNT` — scripts refuse to guess.
  72. ## Usage
  73. The agent runs the scripts for you. To run them by hand, from the skill directory:
  74. ```bash
  75. # Post a tweet
  76. echo '{"content":"Hello world"}' | ./run.sh post
  77. # Post with images
  78. echo '{"content":"Check this out","imagePaths":["/path/to/image.png"]}' | ./run.sh post
  79. # Like a tweet
  80. echo '{"tweetUrl":"https://x.com/user/status/123"}' | ./run.sh like
  81. # Reply to a tweet
  82. echo '{"tweetUrl":"https://x.com/user/status/123","content":"Great post!"}' | ./run.sh reply
  83. # Retweet
  84. echo '{"tweetUrl":"https://x.com/user/status/123"}' | ./run.sh retweet
  85. # Quote tweet
  86. echo '{"tweetUrl":"https://x.com/user/status/123","comment":"Interesting"}' | ./run.sh quote
  87. # Search ("Latest" tab; X search operators work)
  88. echo '{"query":"\"where did I put\" lang:en -filter:replies","limit":20}' | ./run.sh search
  89. # List your own tweets
  90. echo '{"tab":"with_replies","limit":200}' | ./run.sh my-tweets
  91. # List mentions
  92. echo '{"limit":40}' | ./run.sh mentions
  93. # Delete your own tweets by URL
  94. echo '{"tweetUrls":["https://x.com/me/status/123"]}' | ./run.sh delete
  95. # Bulk delete your own tweets matching a regex
  96. echo '{"match":"keyword|other","limit":500}' | ./run.sh purge
  97. # Act as another account
  98. echo '{"content":"Hello"}' | X_ACCOUNT=other_handle ./run.sh post
  99. ```
  100. Output is a JSON line:
  101. ```json
  102. {"success": true, "message": "Tweet posted: https://x.com/user/status/123456"}
  103. ```
  104. ## Configuration
  105. ### Environment Variables
  106. | Variable | Default | Description |
  107. |----------|---------|-------------|
  108. | `CHROME_PATH` | `/Applications/Google Chrome.app/Contents/MacOS/Google Chrome` | Chrome executable path |
  109. | `X_ACCOUNT` | unset (the only account set up) | Handle of the account to act as; required once several are set up |
  110. | `X_HEADLESS` | unset (headful) | `1` runs Chrome headless |
  111. | `X_SOCIAL_HOME` | `.x-social/` at the project root, else `~/.x-social-skill` | Data home; environment only |
  112. Set them in the environment, the project's `.x-social/.env`, or `~/.x-social-skill/.env`, in that order of precedence. Put settings that hold for every project, such as `CHROME_PATH`, in the user-level one.
  113. ### Headless
  114. A headful Chrome window becomes the frontmost application on launch, so an unattended run
  115. steals focus from whoever is using the machine — and keystrokes from other automation land
  116. in Chrome. `X_HEADLESS=1` avoids that: a headless process has no window and never comes
  117. to the front.
  118. Headless Chrome reports itself as `HeadlessChrome/<ver>` in both `navigator.userAgent` and
  119. the `Sec-CH-UA` client hints, which sites read. The launcher overrides both with the headful
  120. user agent, built from the installed Chrome's own major version so it does not drift behind
  121. Chrome updates; on macOS app bundles it reads `Info.plist` without launching Chrome, and
  122. elsewhere it runs a bounded `--version` probe. If that version cannot be read it refuses to launch.
  123. Post, reply and quote results include a confirmed URL or an explicit unknown outcome
  124. (`data.outcome: "unknown"`, `retrySafe: false`). A submit timeout is followed by read-only
  125. verification in a separate page. Never retry an unknown write automatically: check the
  126. thread or account timeline first. Allow at least 300 seconds for submission and verification.
  127. Leave `X_HEADLESS` unset when you want to watch the browser to debug a selector.
  128. ### Timeouts and Limits
  129. `lib/config.ts` in the installed skill holds the following; edits there are lost when the installer runs again:
  130. - Browser navigation timeout (default: 30s)
  131. - Element wait timeout (default: 5s)
  132. - Tweet character limit (default: 280)
  133. - Max images per tweet (default: 4)
  134. - Viewport size (default: 1280x800)
  135. ### Data Directories
  136. Data lives outside the installed skill, which the installer replaces. The data home is `.x-social/` at the root of the git project the agent works in — every worktree of a repository shares the main checkout's — or `~/.x-social-skill/` outside a git project or when `X_SOCIAL_HOME` points there.
  137. | Path (under the data home) | Purpose |
  138. |------|---------|
  139. | `.env` | Settings |
  140. | `accounts/<handle>/profile/` | Chrome profile with the account's login session |
  141. | `accounts/<handle>/auth.json` | Authentication state marker |
  142. The profile holds live session cookies, so anyone who has it is logged in as that account. Setup writes a `.gitignore` into a project's `.x-social/` that ignores everything in it, and refuses to set up into one git already tracks. Never commit or share it; teammates set up their own logins.
  143. Before 1.1.0 the profile lived in `data/` under the working directory; it is not migrated, so run the setup once per account.
  144. ## Troubleshooting
  145. ### Authentication Expired
  146. Re-run the setup and log in with that account; it replaces the account's old session:
  147. ```bash
  148. ./run.sh setup
  149. ```
  150. ### Chrome Fails to Launch
  151. Scripts clear stale Chrome lock files on launch; if launch still fails, make sure no other run is using the same account, then clear them by hand:
  152. ```bash
  153. rm -f .x-social/accounts/<handle>/profile/Singleton{Lock,Socket,Cookie}
  154. ```
  155. ### X UI Selector Changes
  156. If scripts fail with element-not-found errors, X may have updated their UI. Update `config.selectors` in `skills/install/template/x-social/lib/config.ts` and reinstall.
  157. ## License
  158. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.