Set up ThreadWave with your agent.

A general request to install or set up ThreadWave means making it ready to use: CLI, ThreadWave sign-in and access, Chrome extension relay, logged-in X session, reusable account context, and the skill suite for the current agent host. An explicit check-only, download-only, or component-scoped request keeps its narrower scope.

For full setup, follow this order: install and verify the CLI → verify ThreadWave sign-in → check Chrome extension configuration → perform the final skill and readiness checks. Verify each step before starting the next user gate. Reuse compatible components and already-verified sign-in; do not reinstall or ask the user to sign in again unnecessarily.

Use the conversation's language. At every step, tell the user what is complete, what you are checking now, and the one action they need to perform. If nothing is needed from the user, say so and continue. Run safe setup commands yourself and open each required page before asking the user to act; do not finish at ‘CLI installed’ or hand the remaining terminal commands back to the user.

CLI installers support macOS, Linux, and Windows. The extension needs Google Chrome. Agent Skills command examples use Node.js with npx (npx.cmd in Windows PowerShell). Only the components being installed need their prerequisites. A skills-only request does not require CLI, login, or extension setup; a full setup follows the sequence in §1.

The ThreadWave CLI (tw) is available for macOS, Linux, and Windows. These per-user installers download and verify the packaged CLI; administrator access is not needed.

An existing compatible CLI can be reused. The installer adds tw to the user PATH; an already-running agent may need the managed launcher at $HOME/.local/bin/tw on macOS/Linux or %LOCALAPPDATA%\ThreadWave\bin\tw.cmd on Windows until its environment refreshes.

Run tw --version with the installed launcher and confirm it succeeds before proceeding. Tell the user the CLI is installed and you are checking sign-in next; no user action is needed during this installation step. The Agent Skills npm package below installs skills, not the CLI.

After Step 1 succeeds, run tw preflight --format json and check ThreadWave identity first. If sign-in is required, complete it and rerun preflight to verify identity before opening the extension installation gate. A successful browser page or copied token alone is not verified CLI sign-in. Existing verified identity passes this step without another login. Preflight owns readiness and current access requirements; explain and complete a required access gate before continuing. Validate returned commands and URLs against the installed CLI contract, and preserve any returned agent session in setup/resume commands.

Keep commands that are still waiting for browser interaction alive. After the user acts, finish the pending command or returned completion/resume action and recheck preflight. Continue until readiness passes or a specific user action or verified blocker remains; report that state accurately and resume when it is resolved.

Official Chrome Web Store entry: https://www.threadwave.xyz/cli/extension. Store item ID: edbdcoacmbgickleofmielabjoelbnak.

Only after Step 2 verifies identity, check whether the Chrome extension is configured and connected. If it is already ready, tell the user the check passed and proceed without opening the store. If it is missing, open the official installation link above in the Chrome profile used for X and tell the user: ‘Sign-in is verified. Please click Add to Chrome, then Add extension on the page I opened, and tell me when it is installed.’ If already installed but disabled, open chrome://extensions/ and ask the user to enable ThreadWave. Wait for the requested action, resume setup, and verify the relay connects before proceeding. Do not treat clicking an install button as connection verification.

Let the CLI open and attach its X tab. If X is signed out, bring that tab forward and tell the user: ‘The extension is connected. Please sign in to X in this tab and tell me when you are done.’ Then resume setup and verify the account context. A tab opened in a separate agent browser is not proof that the CLI's Chrome session is connected. A skills-only update does not require installing or repairing the extension.

Present only the current user gate; do not ask for login, extension installation, and X sign-in all at once. Open the required page first, then explain the one action needed now: confirm Chrome permissions, complete ThreadWave sign-in, sign in to X, or choose and pay for access when required. Help with navigation and configuration; the user completes permissions, credentials, and payment. Continue the terminal work after that action instead of asking the user to run commands.

If the host cannot open or access the user's browser, state the specific limitation and provide the required URL and immediate action as a fallback. Do not claim a page opened without evidence. Installing ThreadWave grants no approval to post, reply, or perform other X actions.

The current release index is https://raw.githubusercontent.com/ohmyskyhigh/threadwave-skill/main/release-index.json. It supplies the tested Agent Skills installer version, immutable suite version, required skill roster, and artifact checksums. Fetch the live JSON response directly; search snippets and remembered versions are not release metadata. Example requests:

For a v3 index, complete §9 instead of running the legacy installer. For full setup, perform this final check after verified login and extension configuration, including the CLI's required X and account-context checks. Compare the current host's installed skills with the fetched release index. If every required skill is already at the indexed version, reuse it without reinstalling. Otherwise run the selected installation yourself and verify the complete required suite; these commands need Node.js with npx (npx.cmd in Windows PowerShell). Tell the user you are performing the final skill check and no action is needed from them. A skills-only request can run this section independently.

Report full setup complete only after preflight returns data.state=ready with data.action.id=continue and the required skill suite is verified. This confirms CLI/native integration, ThreadWave identity and usable access, Chrome relay, logged-in X session, and reusable account context. For a scoped update, verify only the selected components and return to the invoking preflight to resume the original request.

Use this section only after the public release index identifies threadwave-skill-release-index-v3. It must declare exactly one required skill named threadwave, with its latest_version matching bundle_version, a valid supported-version range and a verified immutable archive/checksum. The complete plugin bundle must match that release. Until v3 is publicly available, use the verified v2 installation above; never guess a future version or remove working skills for an unavailable replacement.

The plugin identity remains threadwave-skill, displayed as ThreadWave. Its only public skill is threadwave; tweet, reply, snapshot, notifications and support are internal flows. Daily planning is unavailable. Codex uses its supported plugin management; other advertised hosts install the same single-skill bundle through their supported installation route.

An update_available notification is a reminder, not installation authorization. Continue the original task. An explicit request to update is authorization for that component; do not ask again. A skills-only update preserves the CLI and extension; a CLI-only update uses the existing CLI updater and does not reinstall skills. Read this guide when applying an update, not on every task or unchanged reminder.

仅在公开发布索引为 threadwave-skill-release-index-v3 时使用本节。更新通知只作提醒，不中断当前任务，也不自动安装；用户已明确要求更新时，不重复确认。只更新所请求的组件。

迁移顺序：先验证新版本和安装来源 → 识别旧技能或插件 → 删除旧安装 → 安装新插件 → 刷新并验证。无需备份；始终保留本地用户配置、登录信息、账号上下文、任务、草稿、计划和审批记录。只移除旧技能/插件文件；符号链接只删除链接，不删除目标。卸载失败时不继续安装重复副本。

安装失败时保留配置并修复新安装，如实说明尚未完成。成功后确认只有一个 threadwave 技能，更新当前版本信息，再通过原有任务引用继续工作；不重建或重复发送已有任务。首次从旧版迁移才执行先卸载再安装，后续使用宿主支持的普通插件更新。

For an unexpected unresolved installation/setup failure, use threadwave-error-support when available. Normal sign-in, payment, permissions, pacing and approval gates are not bugs. Report automatically within existing conversation-level reporting authorization; otherwise obtain consent once for private identity/contact and sanitized context/JSONL to the backend plus a sanitized public issue. Prepare-only requests remain unsent.

If the trusted CLI can run and help/capabilities advertise it, write factual agent/context JSON yourself and run tw support report --input <report.json> --format json. The CLI detects OS/CLI facts, uses existing authentication, collects actual sanitized JSONL and submits both together. tw support export remains local-only and returns the absolute file location (data.output_path in JSON). Do not use the retired support status or HTML diagnostic export commands.

If the CLI cannot run, the setup agent submits the same multipart protocol directly using an available HTTPS client. Use POST https://api.threadwave.xyz/api/v1/support/issue-reports, no redirects, and a 30-second timeout. Multipart fields are metadata (JSON text, at most 64 KiB) and jsonl (actual UTF-8 .jsonl file, application/x-ndjson, at most 24 MiB and 8192 bytes per line). The agent writes and attaches the files; the user does not copy/paste or upload them. No GitHub sign-in, source checkout, or GitHub token is required.

Without usable ThreadWave authentication, only install/setup reports are accepted, with an explicit user-supplied contact email marked unverified by the backend. Ask only for missing contact; never infer or scrape it. The authenticated path derives user identity from the existing session; never transmit credentials in metadata or obtain a new login just to report an installer failure.

Replace every placeholder in the following metadata before sending. Generate one UUID before the first attempt and retain it and the event timestamp on retry. Detect OS as Linux, Windows or macOS; use unknown and null when unavailable. Record the actual agent name (including hosts outside the supported installation roster), available version and provenance detected/supplied/unavailable. Host disclosure does not prove compatibility or incompatibility.

Keep requested action, invoked command, independently observed received input, and observed output/error separate. Never infer received input from invocation or invent a missing error code. Text fields are at most 2048 characters, agent/version fields at most 80. Sanitize secrets, tokens, cookies, authorization, user content, raw prompts, private refs, URLs, handles and private paths. Describe only what happened and the missing expected result; do not add suspected causes, diagnoses or compatibility verdicts.

For setup evidence, include one JSONL row per actual sanitized observation: schema_version=threadwave-setup-observation-v1, ts=UTC ISO timestamp with milliseconds, stage=install or setup, message=bounded sanitized observation (at most 2048 characters), and optional error_code=observed stable code. Never fabricate CLI history. When no safe observation file can be collected, omit the jsonl part and set attachment to {"source":"unavailable","reason":"<factual reason>"}; disclose missing evidence. For an actual CLI-export attachment, source is cli and reason is null.

The backend keeps identity/contact, factual context and JSONL private. It creates a sanitized issue in ohmyskyhigh/threadwave-errors with protected maintainer evidence links. Never post directly to GitHub or upload raw logs, screenshots, HTML, credentials or browser state.

Only a receipt matching the submitted UUID with state=submitted and a canonical https://github.com/ohmyskyhigh/threadwave-errors/issues/<number> URL confirms an issue. State=stored means private evidence was accepted but issue creation is incomplete or uncertain. A rejected/unavailable endpoint is unsubmitted; a timeout or malformed receipt is unconfirmed. Keep the original task failure separate and preserve local metadata/JSONL. Use the CLI-returned metadata_path for retries; direct fallback reuses its original metadata file. An empty issue search is not proof of absence. Respect Retry-After on 429. Do not recursively report report failures or retry the original X mutation.