ihuzaifashoukat / x-use-setup

x-use setup

Configure the requested account conversationally. Skip completed steps and honor
the setup authorization for routine local changes; ask for missing account,
persona or credential choices. Do not use setup as authorization to publish.

1. Verify the install

• Run x-use doctor. It checks the selected Patchright/Playwright browser,
  cookies, LLM key and proxies without launching a browser.

• If working in a checkout, use py -3 scripts/setup_uv.py on Windows or
  python3 scripts/setup_uv.py on macOS/Linux and use the .venv executable.
  Otherwise install pip install x-use-mcp and
  python -m patchright install chromium, then re-run doctor.

• If the MCP server is not registered in this client yet, register it, then
  reload the connection if the client supports it, or ask the user to restart
  the client. Continue tool-dependent work only after tools appear.
  Use the absolute executable path and
  absolute data directory printed by the installer; set X_USE_HOME in the
  MCP server environment so configuration and state stay stable across client
  working directories:

  • Claude Desktop (claude_desktop_config.json):
    {"mcpServers": {"x-use": {"command": "/absolute/path/to/x-use/.venv/bin/x-use", "args": ["mcp"], "env": {"X_USE_HOME": "/absolute/path/to/x-use-data"}}}}

  • Cursor, Windsurf, and other clients using mcpServers JSON: use the same
    command, args, and env fields shown for Claude Desktop.

  • Claude Code: claude mcp add --scope user x-use --env X_USE_HOME=/absolute/path/to/x-use-data -- /absolute/path/to/x-use/.venv/bin/x-use mcp

  • Codex (~/.codex/config.toml):
    [mcp_servers.x-use] with the absolute command path and args = ["mcp"],
    plus [mcp_servers.x-use.env] with X_USE_HOME = "/absolute/path/to/x-use-data".

2. Account + cookies

Ask: "What should this account be called (a short id like main or
brand)?" Then explain cookie export:

1. Install a cookie-export browser extension (e.g. "Cookie-Editor").
2. Log into x.com in that browser, open the extension on x.com, Export as JSON.
3. Save the file somewhere on this machine and give me the path.

Then call add_account(account_id, cookie_file=<path>). The file is
validated and copied server-side; cookie values never pass through the chat.
Verify with get_account_health(account); it checks the local cookie file,
not whether X currently accepts the session. Inspect reported problems and use
a bounded browser read to verify login; stop for login or account challenges.

3. Niche and keywords

Ask for the niche, keywords, target profiles and the account's actual X handle.
Apply with
`updateaccount(account, targetkeywords=[...],
competitorprofiles=[...], selfhandles=["yourhandle"]).self_handles` enables
the own-post guard. Batch account edits where possible: each update closes its
warm browser session.

4. Persona

Ask how they want to sound. In a checkout, the personas in presets/personas/
(builder, founder, curator) can serve as starting points; these presets are not
included in the installed skill pack. Otherwise draft the requested voice, then
apply with
update_account(account, persona=<text>). Keep it under 4000 chars,
markdown, covering: voice, topics, reply style, what to avoid, 1-2 example
replies.

5. Optional extras (only if relevant)

• Multi-account: repeat from step 2, and ask about proxies, added with
  add_proxy(pool, proxy_url) and assign with
  update_account(account, proxy="pool:<name>").

• Server-generated posts/replies and unattended "auto" text need one
  OpenAI-compatible key in config/settings.json under llm
  (api_key, base_url, model). Interactive use needs no key at all.

6. Prove it works

With mcp.draft_mode=true (default), use x-use-engage or x-use-content to stage
one requested reply or post and show its full payload. Ordinary writes execute
immediately when draft mode is disabled. approve_draft executes reviewed
drafts; queued actions run via process_queue or opt-in auto-drain, and legacy
run_cycle runs immediately. Preparation alone does not authorize those gates.

Use x-use-inbox for requested message and notification workflows.
Requested inbox verification uses `get_inbox(account=..., folder="inbox",
inbox_filter="unread", limit=5)`; requests and other folders are separate, and
results cover only visible conversations. Reads never accept requests.
unread=null means the UI supplied no reliable read-state evidence. Opening a
chat may mark it as read; visiting notifications can do the same. If
pin_required, use unlock_inbox(account=..., pin_env_var="XUSE_INBOX_PIN")
after the owner sets that server variable; never request a PIN in chat or store it
in drafts. Stop for unsupported UI or account challenges. Messages and follows
always need individual draft approval, and an uncertain write needs explicit
outcome reconciliation after inspecting X before any retry.