/x-integration

name: x-integration
description: X (Twitter) integration for ClaudeClaw. Post tweets, like, reply, retweet, and quote. Use for setup, testing, or troubleshooting X functionality. Triggers on "setup x", "x integration", "twitter", "post tweet", "tweet".

X (Twitter) Integration

Browser automation for X interactions via WhatsApp.

> **Compatibility:** ClaudeClaw v1.0.0. Directory structure may change in future versions.

Features

| Action | Tool | Description | |--------|------|-------------| | Post | `x_post` | Publish new tweets | | Like | `x_like` | Like any tweet | | Reply | `x_reply` | Reply to tweets | | Retweet | `x_retweet` | Retweet without comment | | Quote | `x_quote` | Quote tweet with comment |

Prerequisites

Before using this skill, ensure:

1. **ClaudeClaw is installed and running** - WhatsApp connected, service active 2. **Dependencies installed**:

   npm ls playwright dotenv-cli || npm install playwright dotenv-cli

3. **CHROME_PATH configured** in `.env` (if Chrome is not at default location):

   # Find your Chrome path
   mdfind "kMDItemCFBundleIdentifier == 'com.google.Chrome'" 2>/dev/null | head -1
   # Add to .env
   CHROME_PATH=/path/to/Google Chrome.app/Contents/MacOS/Google Chrome

> **Service name:** Derived from the directory name: `com.claudeclaw.<dirname>` (macOS) / `claudeclaw-<dirname>` (Linux). For example, if cwd is `my-assistant`, the service is `com.claudeclaw.my-assistant`. Determine the correct service name before running service commands below.

Quick Start

# 1. Setup authentication (interactive)
npx dotenv -e .env -- npx tsx .claude/skills/x-integration/scripts/setup.ts
# Verify: data/x-auth.json should exist after successful login

# 2. Rebuild container to include skill
./src/runtimes/docker/build.sh
# Verify: Output shows "COPY .claude/skills/x-integration/agent.ts"

# 3. Rebuild host and restart service
# Service name: In developer mode use com.claudeclaw / claudeclaw.
# Service name derived from directory name: com.claudeclaw.<dirname> / claudeclaw-<dirname>.
npm run build
launchctl kickstart -k gui/$(id -u)/com.claudeclaw  # macOS
# Linux: systemctl --user restart claudeclaw
# Verify: launchctl list | grep claudeclaw (macOS) or systemctl --user status claudeclaw (Linux)

Configuration

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | `CHROME_PATH` | `/Applications/Google Chrome.app/Contents/MacOS/Google Chrome` | Chrome executable path | | `CLAUDECLAW_ROOT` | `process.cwd()` | Project root directory | | `LOG_LEVEL` | `info` | Logging level (debug, info, warn, error) |

Set in `.env` file (loaded via `dotenv-cli` at runtime):

# .env
CHROME_PATH=/Applications/Google Chrome.app/Contents/MacOS/Google Chrome

Configuration File

Edit `lib/config.ts` to modify defaults:

export const config = {
    // Browser viewport
    viewport: { width: 1280, height: 800 },

    // Timeouts (milliseconds)
    timeouts: {
        navigation: 30000,    // Page navigation
        elementWait: 5000,    // Wait for element
        afterClick: 1000,     // Delay after click
        afterFill: 1000,      // Delay after form fill
        afterSubmit: 3000,    // Delay after submit
        pageLoad: 3000,       // Initial page load
    },

    // Tweet limits
    limits: {
        tweetMaxLength: 280,
    },
};

Data Directories

Paths relative to project root:

| Path | Purpose | Git | |------|---------|-----| | `data/x-browser-profile/` | Chrome profile with X session | Ignored | | `data/x-auth.json` | Auth state marker | Ignored | | `logs/claudeclaw.log` | Service logs (contains X operation logs) | Ignored |

Architecture

┌─────────────────────────────────────────────────────────────┐
│  Container (Linux VM)                                       │
│  └── agent.ts → MCP tool definitions (x_post, etc.)    │
│      └── Writes IPC request to /workspace/ipc/tasks/       │
└──────────────────────┬──────────────────────────────────────┘
                       │ IPC (file system)
                       ▼
┌─────────────────────────────────────────────────────────────┐
│  Host (macOS)                                               │
│  └── src/orchestrator/ipc.ts → processTaskIpc()                         │
│      └── host.ts → handleXIpc()                         │
│          └── spawn subprocess → scripts/*.ts               │
│              └── Playwright → Chrome → X Website           │
└─────────────────────────────────────────────────────────────┘

Why This Design?

• **API is expensive** - X official API requires paid subscription ($100+/month) for posting
• **Bot browsers get blocked** - X detects and bans headless browsers and common automation fingerprints
• **Must use user's real browser** - Reuses the user's actual Chrome on Host with real browser fingerprint to avoid detection
• **One-time authorization** - User logs in manually once, session persists in Chrome profile for future use

File Structure

.claude/skills/x-integration/
├── SKILL.md          # This documentation
├── host.ts           # Host-side IPC handler
├── agent.ts          # Container-side MCP tool definitions
├── lib/
│   ├── config.ts     # Centralized configuration
│   └── browser.ts    # Playwright utilities
└── scripts/
    ├── setup.ts      # Interactive login
    ├── post.ts       # Post tweet
    ├── like.ts       # Like tweet
    ├── reply.ts      # Reply to tweet
    ├── retweet.ts    # Retweet
    └── quote.ts      # Quote tweet

Integration Points

To integrate this skill into ClaudeClaw, make the following modifications:

---

**1. Host side: `src/orchestrator/ipc.ts`**

Add import after other local imports:

import { handleXIpc } from '../.claude/skills/x-integration/host.js';

Modify `processTaskIpc` function's switch statement default case:

// Find:
default:
logg