X (Twitter) Integration

Browser automation for X interactions via WhatsApp.

Compatibility: NanoClawbster v1.0.0. Directory structure may change in future versions.

Features

Prerequisites

Before using this skill, ensure:

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

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

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

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

Quick Start

bash
1# 1. Setup authentication (interactive)
2npx dotenv -e .env -- npx tsx .claude/skills/x-integration/scripts/setup.ts
3# Verify: data/x-auth.json should exist after successful login
4
5# 2. Rebuild container to include skill
6./container/build.sh
7# Verify: Output shows "COPY .claude/skills/x-integration/agent.ts"
8
9# 3. Rebuild host and restart service
10npm run build
11launchctl kickstart -k gui/$(id -u)/com.nanoclawbster  # macOS
12# Linux: systemctl --user restart nanoclawbster
13# Verify: launchctl list | grep nanoclawbster (macOS) or systemctl --user status nanoclawbster (Linux)

Configuration

Environment Variables

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

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

Configuration File

Edit lib/config.ts to modify defaults:

typescript
1export const config = {
2    // Browser viewport
3    viewport: { width: 1280, height: 800 },
4
5    // Timeouts (milliseconds)
6    timeouts: {
7        navigation: 30000,    // Page navigation
8        elementWait: 5000,    // Wait for element
9        afterClick: 1000,     // Delay after click
10        afterFill: 1000,      // Delay after form fill
11        afterSubmit: 3000,    // Delay after submit
12        pageLoad: 3000,       // Initial page load
13    },
14
15    // Tweet limits
16    limits: {
17        tweetMaxLength: 280,
18    },
19};

Data Directories

Paths relative to project root:

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/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 NanoClawbster, make the following modifications:

1. Host side: src/ipc.ts

Add import after other local imports:

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

Modify processTaskIpc function's switch statement default case:

typescript
1// Find:
2default:
3logger.warn({ type: data.type }, 'Unknown IPC task type');
4
5// Replace with:
6default:
7const handled = await handleXIpc(data, sourceGroup, isAdmin, DATA_DIR);
8if (!handled) {
9    logger.warn({ type: data.type }, 'Unknown IPC task type');
10}

2. Container side: container/agent-runner/src/ipc-mcp.ts

Add import after cron-parser import:

typescript
1// @ts-ignore - Copied during Docker build from .claude/skills/x-integration/
2import { createXTools } from './skills/x-integration/agent.js';

Add to the end of tools array (before the closing ]):

typescript
1    ...createXTools({ groupFolder, isAdmin })

3. Build script: container/build.sh

Change build context from container/ to project root (required to access .claude/skills/):

bash
1# Find:
2docker build -t "${IMAGE_NAME}:${TAG}" .
3
4# Replace with:
5cd "$SCRIPT_DIR/.."
6docker build -t "${IMAGE_NAME}:${TAG}" -f container/Dockerfile .

4. Dockerfile: container/Dockerfile

First, update the build context paths (required to access .claude/skills/ from project root):

dockerfile
1# Find:
2COPY agent-runner/package*.json ./
3...
4COPY agent-runner/ ./
5
6# Replace with:
7COPY container/agent-runner/package*.json ./
8...
9COPY container/agent-runner/ ./

Then add COPY line after COPY container/agent-runner/ ./ and before RUN npm run build:

dockerfile
1# Copy skill MCP tools
2COPY .claude/skills/x-integration/agent.ts ./src/skills/x-integration/

Setup

All paths below are relative to project root (NANOCLAWBSTER_ROOT).

1. Check Chrome Path

bash
1# Check if Chrome exists at configured path
2cat .env | grep CHROME_PATH
3ls -la "$(grep CHROME_PATH .env | cut -d= -f2)" 2>/dev/null || \
4echo "Chrome not found - update CHROME_PATH in .env"

2. Run Authentication

bash
1npx dotenv -e .env -- npx tsx .claude/skills/x-integration/scripts/setup.ts

This opens Chrome for manual X login. Session saved to data/x-browser-profile/.

Verify success:

bash
1cat data/x-auth.json  # Should show {"authenticated": true, ...}

3. Rebuild Container

bash
1./container/build.sh

Verify success:

bash
1./container/build.sh 2>&1 | grep -i "agent.ts"  # Should show COPY line

4. Restart Service

bash
1npm run build
2launchctl kickstart -k gui/$(id -u)/com.nanoclawbster  # macOS
3# Linux: systemctl --user restart nanoclawbster

Verify success:

bash
1launchctl list | grep nanoclawbster  # macOS — should show PID and exit code 0 or -
2# Linux: systemctl --user status nanoclawbster

Usage via WhatsApp

Replace @Assistant with your configured trigger name (ASSISTANT_NAME in .env):

@Assistant post a tweet: Hello world!

@Assistant like this tweet https://x.com/user/status/123

@Assistant reply to https://x.com/user/status/123 with: Great post!

@Assistant retweet https://x.com/user/status/123

@Assistant quote https://x.com/user/status/123 with comment: Interesting

Note: Only the main group can use X tools. Other groups will receive an error.

Testing

Scripts require environment variables from .env. Use dotenv-cli to load them:

Check Authentication Status

bash
1# Check if auth file exists and is valid
2cat data/x-auth.json 2>/dev/null && echo "Auth configured" || echo "Auth not configured"
3
4# Check if browser profile exists
5ls -la data/x-browser-profile/ 2>/dev/null | head -5

Re-authenticate (if expired)

bash
1npx dotenv -e .env -- npx tsx .claude/skills/x-integration/scripts/setup.ts

Test Post (will actually post)

bash
1echo '{"content":"Test tweet - please ignore"}' | npx dotenv -e .env -- npx tsx .claude/skills/x-integration/scripts/post.ts

Test Like

bash
1echo '{"tweetUrl":"https://x.com/user/status/123"}' | npx dotenv -e .env -- npx tsx .claude/skills/x-integration/scripts/like.ts

Or export CHROME_PATH manually before running:

bash
1export CHROME_PATH="/path/to/chrome"
2echo '{"content":"Test"}' | npx tsx .claude/skills/x-integration/scripts/post.ts

Troubleshooting

Authentication Expired

bash
1npx dotenv -e .env -- npx tsx .claude/skills/x-integration/scripts/setup.ts
2launchctl kickstart -k gui/$(id -u)/com.nanoclawbster  # macOS
3# Linux: systemctl --user restart nanoclawbster

Browser Lock Files

If Chrome fails to launch:

bash
1rm -f data/x-browser-profile/SingletonLock
2rm -f data/x-browser-profile/SingletonSocket
3rm -f data/x-browser-profile/SingletonCookie

Check Logs

bash
1# Host logs (relative to project root)
2grep -i "x_post\|x_like\|x_reply\|handleXIpc" logs/nanoclawbster.log | tail -20
3
4# Script errors
5grep -i "error\|failed" logs/nanoclawbster.log | tail -20

Script Timeout

Default timeout is 2 minutes (120s). Increase in host.ts:

typescript
1const timer = setTimeout(() => {
2  proc.kill('SIGTERM');
3  resolve({ success: false, message: 'Script timed out (120s)' });
4}, 120000);  // ← Increase this value

X UI Selector Changes

If X updates their UI, selectors in scripts may break. Current selectors:

Container Build Issues

If MCP tools not found in container:

bash
1# Verify build copies skill
2./container/build.sh 2>&1 | grep -i skill
3
4# Check container has the file
5docker run nanoclawbster-agent ls -la /app/src/skills/

Security

• data/x-browser-profile/ - Contains X session cookies (in .gitignore)
• data/x-auth.json - Auth state marker (in .gitignore)
• Only main group can use X tools (enforced in agent.ts and host.ts)
• Scripts run as subprocesses with limited environment