1# Regular Posts - Detailed Guide
2 
3Detailed documentation for posting text and images to X.
4 
5## Manual Workflow
6 
7If you prefer step-by-step control:
8 
9### Step 1: Copy Image to Clipboard
10 
11```bash
12${BUN_X} {baseDir}/scripts/copy-to-clipboard.ts image /path/to/image.png
13```
14 
15### Step 2: Paste from Clipboard
16 
17```bash
18# Simple paste to frontmost app
19${BUN_X} {baseDir}/scripts/paste-from-clipboard.ts
20 
21# Paste to Chrome with retries
22${BUN_X} {baseDir}/scripts/paste-from-clipboard.ts --app "Google Chrome" --retries 5
23 
24# Quick paste with shorter delay
25${BUN_X} {baseDir}/scripts/paste-from-clipboard.ts --delay 200
26```
27 
28### Step 3: Use Playwright MCP (if Chrome session available)
29 
30```bash
31# Navigate
32mcp__playwright__browser_navigate url="https://x.com/compose/post"
33 
34# Get element refs
35mcp__playwright__browser_snapshot
36 
37# Type text
38mcp__playwright__browser_click element="editor" ref="<ref>"
39mcp__playwright__browser_type element="editor" ref="<ref>" text="Your content"
40 
41# Paste image (after copying to clipboard)
42mcp__playwright__browser_press_key key="Meta+v"  # macOS
43# or
44mcp__playwright__browser_press_key key="Control+v"  # Windows/Linux
45 
46# Screenshot to verify
47mcp__playwright__browser_take_screenshot filename="preview.png"
48```
49 
50## Image Support
51 
52- Formats: PNG, JPEG, GIF, WebP
53- Max 4 images per post
54- Images copied to system clipboard, then pasted via keyboard shortcut
55 
56## Example Session
57 
58```
59User: /post-to-x "Hello from Claude!" --image ./screenshot.png
60 
61Claude:
621. Runs: ${BUN_X} {baseDir}/scripts/x-browser.ts "Hello from Claude!" --image ./screenshot.png
632. Chrome opens with X compose page
643. Text is typed into editor
654. Image is copied to clipboard and pasted
665. Browser stays open 30s for preview
676. Reports: "Post composed. Use --submit to post."
68```
69 
70## Troubleshooting
71 
72- **Chrome not found**: Set `X_BROWSER_CHROME_PATH` environment variable
73- **Not logged in**: First run opens Chrome - log in manually, cookies are saved
74- **Image paste fails**:
75  - Verify clipboard script: `${BUN_X} {baseDir}/scripts/copy-to-clipboard.ts image <path>`
76  - On macOS, grant "Accessibility" permission to Terminal/iTerm in System Settings > Privacy & Security > Accessibility
77  - Keep Chrome window visible and in front during paste operations
78- **osascript permission denied**: Grant Terminal accessibility permissions in System Preferences
79- **Rate limited**: Wait a few minutes before retrying
80 
81## How It Works
82 
83The `x-browser.ts` script uses Chrome DevTools Protocol (CDP) to:
841. Launch real Chrome (not Playwright) with `--disable-blink-features=AutomationControlled`
852. Use persistent profile directory for saved login sessions
863. Interact with X via CDP commands (Runtime.evaluate, Input.dispatchKeyEvent)
874. **Paste images using osascript** (macOS): Sends real Cmd+V keystroke to Chrome, bypassing CDP's synthetic events that X can detect
88 
89This approach bypasses X's anti-automation detection that blocks Playwright/Puppeteer.
90 
91### Image Paste Mechanism (macOS)
92 
93CDP's `Input.dispatchKeyEvent` sends "synthetic" keyboard events that websites can detect. X ignores synthetic paste events for security. The solution:
94 
951. Copy image to system clipboard via Swift/AppKit (`copy-to-clipboard.ts`)
962. Bring Chrome to front via `osascript`
973. Send real Cmd+V keystroke via `osascript` and System Events
984. Wait for upload to complete
99 
100This requires Terminal to have "Accessibility" permission in System Settings.
101