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:

• NanoClaw is installed and running - WhatsApp connected, service active

• Dependencies installed: npm ls playwright dotenv-cli || npm install playwright dotenv-cli

• 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

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

./container/build.sh

Verify: Output shows "COPY .claude/skills/x-integration/agent.ts"

3. Rebuild host and restart service

npm run build launchctl kickstart -k gui/$(id -u)/com.nanoclaw # macOS

Linux: systemctl --user restart nanoclaw

Verify: launchctl list | grep nanoclaw (macOS) or systemctl --user status nanoclaw (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 npm 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

npx 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:

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

npm run build launchctl kickstart -k gui/$(id -u)/com.nanoclaw # macOS

Linux: systemctl --user restart nanoclaw

Verify success:

launchctl list | grep nanoclaw # macOS — should show PID and exit code 0 or -

Linux: systemctl --user status nanoclaw

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

Check if auth file exists and is valid

cat data/x-auth.json 2>/dev/null && echo "Auth configured" || echo "Auth not configured"

Check if browser profile exists

ls -la data/x-browser-profile/ 2>/dev/null | head -5

Re-authenticate (if expired)

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

Test Post (will actually post)

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

Test Like

echo '{"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:

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

Troubleshooting

Authentication Expired

npx dotenv -e .env -- npx tsx .claude/skills/x-integration/scripts/setup.ts launchctl kickstart -k gui/$(id -u)/com.nanoclaw # macOS

Linux: systemctl --user restart nanoclaw

Browser Lock Files

If Chrome fails to launch:

rm -f data/x-browser-profile/SingletonLock rm -f data/x-browser-profile/SingletonSocket rm -f data/x-browser-profile/SingletonCookie

Check Logs

Host logs (relative to project root)

grep -i "x_post|x_like|x_reply|handleXIpc" logs/nanoclaw.log | tail -20

Script errors

grep -i "error|failed" logs/nanoclaw.log | tail -20

Script Timeout

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

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

X UI Selector Changes

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

Element Selector

Tweet input [data-testid="tweetTextarea_0"]

Post button [data-testid="tweetButtonInline"]

Reply button [data-testid="reply"]

Like [data-testid="like"]

Unlike [data-testid="unlike"]

Retweet [data-testid="retweet"]

Unretweet [data-testid="unretweet"]

Confirm retweet [data-testid="retweetConfirm"]

Modal dialog [role="dialog"][aria-modal="true"]

Modal submit [data-testid="tweetButton"]

Container Build Issues

If MCP tools not found in container:

Verify build copies skill

./container/build.sh 2>&1 | grep -i skill

Check container has the file

docker run nanoclaw-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