x-integration

X (Twitter) Integration

Browser automation for X interactions via WhatsApp.

Compatibility: NanoClaw 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. NanoClaw is installed and running - WhatsApp connected, service active
2. Dependencies installed:

``bash pnpm ls playwright dotenv-cli || pnpm install playwright dotenv-cli ``

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

``bash # 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 ``

Quick Start

Run from your NanoClaw project root:

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

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

# 3. Rebuild host and restart service
pnpm run build
source setup/lib/install-slug.sh
launchctl kickstart -k gui/$(id -u)/$(launchd_label)  # macOS
# Linux: systemctl --user restart $(systemd_unit)
# Verify: launchctl list | grep "$(launchd_label)" (macOS) or systemctl --user status $(systemd_unit) (Linux)

Configuration

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | CHROME_PATH | /Applications/Google Chrome.app/Contents/MacOS/Google Chrome | Chrome executable path | | NANOCLAW_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/nanoclaw.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/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 NanoClaw, make the following modifications:

1. Host side: src/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:
logger.warn({ type: data.type }, 'Unknown IPC task type');

// Replace with:
default:
const handled = await handleXIpc(data, sourceGroup, isMain, DATA_DIR);
if (!handled) {
    logger.warn({ type: data.type }, 'Unknown IPC task type');
}

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

Add import after cron-parser import:

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

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

    ...createXTools({ groupFolder, isMain })

3. Build script: container/build.sh

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

# Find:
docker build -t "${IMAGE_NAME}:${TAG}" .

# Replace with:
cd "$SCRIPT_DIR/.."
docker 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):

# Find:
COPY agent-runner/package*.json ./
...
COPY agent-runner/ ./

# Replace with:
COPY container/agent-runner/package*.json ./
...
COPY container/agent-runner/ ./

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

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

Setup

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

1. Check Chrome Path

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

2. Run Authentication

pnpm exec dotenv -e .env -- pnpm exec tsx .claude/skills/x-integration/scripts/setup.ts

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

Verify success:

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

3. Rebuild Container

./container/build.sh

Verify success:

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

4. Restart Service

Run from your NanoClaw project root:

pnpm run build
source setup/lib/install-slug.sh
launchctl kickstart -k gui/$(id -u)/$(launchd_label)  # macOS
# Linux: systemctl --user restart $(systemd_unit)

Verify success.

Run from your NanoClaw project root:

source setup/lib/install-slug.sh
launchctl list | grep "$(launchd_label)"  # macOS — should sh