Windy Word

Execute the auto-paste flow against an explicit candidate chain. Returns the winning strategy + per-strategy diagnostic data. Useful for stress-testing fallback behavior. WARNING: injects text into the focused window.

Wipe the in-memory install audit log. Useful between test runs.

Reset the in-memory paste history buffer. Useful between stress-test runs.

Wipe the entire translation-memory cache. Destructive — confirm with the user before calling.

Run local diagnostics AND route the findings to the windy-fix-me cloud-relay for LLM-augmented remediation. Returns both the local rule-based findings and the cloud-relay's structured remediation (each entry has rootCause, a specific MCP tool call to invoke, fallback, verification steps). Use this when local run_diagnostics surfaces warnings/errors and you want expert-level fix guidance that knows about platform-specific quirks the local rules don't. Relay endpoint: https://windy-fix-me.windyword.workers.dev/diagnose (override via WINDY_FIX_ME_URL env var on the Windy Word side). May add ~2-3s of latency from the LLM round-trip.

Create a voice clone from an audio file on disk. Copies the source file into Windy Word's voice-samples directory under a fresh UUID, registers the clone in the local DB, and returns the new clone's metadata (with hasAudio=true). Supported audio extensions: .webm, .wav, .mp3, .ogg, .m4a, .flac. Source file must exist and be readable; the copy itself is path-confined to Windy's voice-samples dir. Use list_voice_clones afterward to see it and set_active_voice_clone to activate.

Tear down an archive entry: removes the transcript .md file + linked audio + linked video, all path-confined to the archive folder. Irreversible — confirm with the user before calling. Returns the list of filenames actually deleted.

Delete a voice clone (metadata + audio file on disk). If the deleted clone was the active one, activeId is reset to null. Returns the deleted clone's id and name for audit purposes. Irreversible — confirm with the user before calling.

Return the full catalog entry for one setting (type / allowed values / description / default / side effects / restartRequired / sensitivity) plus its current value from the live store. Returns an error if the path is not in the catalog — use get_config for paths outside it.

Return system hardware info: totalRAM (GB), freeRAM (GB), cpuModel, cpuCores, platform, arch, gpu (NVIDIA via nvidia-smi on Linux/Windows; Apple Silicon Metal/MPS on macOS arm64; null otherwise), diskFreeGB (homedir partition). Used by Doctor checks and model-selection decisions — bigger models need more RAM, GPU-accelerated paths only fire when gpu != null.

Export the user's entire Windy Word archive (audio + video + transcripts) as a single zip file at the given path. The Forma Animae artifact — Grant's exportable "soul" for use with the Windy Clone digital-twin pipeline or as a portable backup. Includes a manifest.json with stats (file counts, word counts, date range). Refuses to overwrite existing files unless overwrite=true. Creates parent directories as needed. Pairs with the existing export-soul-file IPC the renderer uses via the Soul File button (which opens a save dialog) — this is the path-based variant for agent-driven exports.

Extract plain text from a document file at a given path. Supports .txt / .md / .csv (read as UTF-8), .html (strip tags), .pdf (regex scrape — best-effort, may return [PDF text extraction yielded nothing] for image-only PDFs), .docx (xml-strip). Default size cap 5MB; override via maxBytes (up to 20MB). Returns {ok, path, ext, sizeBytes, textLength, text}.

Return the currently selected paste strategy, the user-configured fallback chain, and the resolved chain that will actually be tried at paste time. When strategy is "auto", the chain comes from defaultFallbackChain() with hotkey-collision demotion applied.

Return the currently-active voice clone (the one used for TTS playback), or {active: null} if no clone is selected.

Return aggregate stats for the user's recording archive: totalFiles, totalSizeMB, days (number of distinct date directories), audioHours, videoHours, totalWords, totalSessions, totalChars. Cached server-side for 30s — responses include `cached` + `cacheAgeSec` so the agent knows freshness.

Check whether Windy Word is configured to auto-launch on user login. Returns {platform, enabled, desktopFile?}. Linux checks for ~/.config/autostart/windy-pro.desktop; macOS/Windows use electron's app.getLoginItemSettings(). Pure read — no state change.

Check the status of a Windy Clone cloud-training order — used after submit_voice_clone_to_cloud (Phase 2 — not yet exposed as MCP) to poll for ElevenLabs training completion. Requires the user to be signed in to their Windy account; returns a clean 401-shape error if not. Returns the raw order body from the Windy Clone API.

Return the full electron-store config tree (every setting Windy Word has persisted). Large but read-only — use this to discover what setting paths exist before set_config.

Return the audit log of recent install_dependency attempts on this machine (timestamp, tool, package, exact command, exit code, elapsed ms, whether the tool is on PATH after, stdout/stderr tails). In-memory; resets when Windy Word restarts.

Return the current state of an async install job started by install_dependency_async. Status is "running" (still in flight) or "completed" (finished — check result.ok for success). If the job is not found (FIFO-evicted after 50 jobs, or wrong jobId), returns status="unknown".

Return the last N paste attempts with diagnostic data: timestamp, text length, content hash (NOT the actual text), strategy chain attempted, winner, target window type. The buffer is in-memory and resets when the app restarts.

Detect whether the currently focused window is XWayland or Wayland-native (or unknown). This is what xdotool sees — agents use it to verify their assumptions before picking a strategy, because XWayland targets accept different keystrokes than Wayland-native ones.

Return OS / arch / distro / display-server / desktop-environment / tool-availability info for the machine running Windy Word. Use this first when diagnosing paste / hotkey issues — the platform determines which strategies and capabilities are valid.

Return the current sound-effects configuration: per-hook-stage enabled/volume settings (the 6 stages are start, during, stop, process, warning, paste), the active sound pack, master SFX volume, and any per-stage custom sound overrides. The 6 hookStages are always returned even when live state read fails (so agents can show the stage catalog). **Phase 1 limitation:** Sound state lives in renderer-side localStorage, not the main electron-store. Reading via webContents.executeJavaScript currently fails (Electron context-isolation) — expect rendererReadable=false with rendererError set. Phase 2 will add a renderer-side IPC bridge in windy-pro to expose live state + writes.

Return TM cache stats: totalEntries, topPairs (top 10 source→target language pairs by count), recentEntries (last 50 by updated_at).

Return mini-widget (tornado) runtime state via the renderer bridge: whether the WidgetEngine is present, whether the widget is currently visible, and the localStorage tornadoSize value. Complements the catalog-driven set_setting path for tornadoX/tornadoY/tornadoSize/widgetSettings.

Return WindyTune auto-tune state: whether it is enabled, the current model, the model ladder, switch thresholds, the recent transcription timing history, and the rolling average ratio (used to decide when to climb or descend the ladder).

Install a missing system tool via the distro package manager wrapped in pkexec. WARNING: this triggers a graphical sudo (polkit) prompt that the user must approve interactively — do not call without telling the user a prompt will appear. The tool must be in Windy Word's whitelist: wtype, ydotool, wl-clipboard, xdotool. Linux only. After a successful install of wtype, re-check list_paste_strategies — wtype will flip to availableOnThisMachine=true and become first-pick in the resolved chain (paste becomes instant on Wayland-native targets). Use dryRun=true to see the command without executing it.

Fire-and-poll variant of install_dependency. Returns a jobId immediately and runs the install in the background. Use get_install_status to check progress. Useful when the install might take >10 minutes (e.g., compiling from source, large package downloads on slow networks) or when the agent wants to surface a "still installing…" UI without holding a connection open. The whitelist + platform constraints + polkit/sudo flow are identical to install_dependency.

List archived recording sessions (the user's historical transcripts + linked audio/video). Each entry has an opaque id (use it with read_archive or delete_archive_entry), date, full transcript text, wordCount, engine used, and hasAudio / hasVideo booleans. Newest first. Path information is NOT returned — agents work with the opaque id.

List training-bundle catalog — audio/video recordings the user has marked as candidates for voice-clone training. Each entry has bundle_id, name, device info, sync_status, training_ready flag, file size, created_at, and fileExists. Pairs with InstaBio voice-clone ingestion which reads from these bundles. See [[project_instabio_voice_clone_data]] memory for the broader voice-clone training-data contract.

List the catalog of Windy Doctor diagnostic checks without running them. Returns each check's name, description, and whether it applies to this platform. Useful for agent introspection — understanding what the doctor knows how to look at before kicking off a diagnostic run.

List all current keyboard shortcut bindings, the set of rebindable actions, and the list of accelerators that are reserved (cannot be assigned). Use this before set_hotkey.

List all install jobs currently in memory — both running and recently completed. Useful for dashboards or when an agent forgot a jobId.

List the whitelisted system tools that Windy Word can install on this machine to expand its capabilities (e.g. wtype for instant Wayland paste). Returns supported platform check + distro detection + the resolved install command per tool. Always safe to call (no system mutation). v0 supports Linux only — returns supported=false with a friendly explanation on macOS/Windows.

List available Whisper transcription models (tiny / base / small / medium / large-v3), their on-disk size and accuracy/speed tradeoff, the current selected model, and the WindyTune ladder.

List all 12 paste strategies (macOS / Windows / Linux X11 / Linux Wayland) with full capability metadata, a per-strategy availableOnThisMachine flag, the resolved default fallback chain, and a hotkeyCollisionDetected flag indicating whether Mutter or another compositor is eating Windy Word's own paste keystroke (which silently breaks the Ctrl+Shift+V family on Wayland+GNOME).

List every setting Windy Word exposes as an agent-discoverable, schema-validated path. Returns each setting's dotted path, type, description, allowed values (if enum / range), default, side effects of changing it, restartRequired flag, sensitivity (writable vs readonly), tags, and the current live value. The response also includes availableTags so agents can discover what tag filters exist. Use this as the entry point for any agent setting introspection. Paths outside the catalog are accessible only via the lower-level get_config / set_config tools. Optional `tag` parameter narrows results — e.g. tag="voice-clone" returns just the settings that drive InstaBio voice-clone training behavior, tag="archive" returns archive-related settings, etc.

List the sound-effect packs the Windy Word EffectsEngine knows about (_silent, classic-beep, soft-chime, and other built-in synthesized packs). Pairs with the 6 hook stages (start/during/stop/process/warning/paste) to drive per-stage sound assignments. **Phase 1 limitation:** Same as get_sound_effect_state — the renderer EffectsEngine isn't globally exposed, so live pack-list queries return ok=false until Phase 2 (renderer-side IPC bridge). The endpoint shape is finalized for forward-compat.

List all voice clones the user has on this machine. Returns each clone's id, name, duration, created_at, status, plus a hasAudio boolean (no raw audio in the response — use preview_voice_clone to fetch base64 audio for a specific clone). Also returns activeId — which clone is the current TTS default. Use this to answer "what clones does the user have?" without paging through audio bytes.

Look up a (text, sourceLang, targetLang) tuple in the local translation-memory cache. Returns {ok, match: {translation, hits} | null}. No external API call — pure local SQLite query.

Pop the archive root directory in the user's OS file manager. Side-effect on the desktop (opens a Files / Finder / Explorer window). Use when the user asks "show me where my recordings are saved" or similar.

Re-paste the most recent transcript into the focused window (same effect as the paste-transcript hotkey). Does NOT start a new recording.

Return a voice clone's metadata, optionally with the base64-encoded audio sample. Pass metadataOnly=true to skip the audio (responses can be several MB otherwise). The mimeType field tells the agent how to interpret audioBase64 (typically audio/webm).

Open the Quick Translate mini-window.

Return an archive entry's metadata + optionally the base64 audio or video media bytes. The mediaType parameter selects which stream ("audio" default, or "video"). Pass metadataOnly=true to skip the base64 payload (responses can be MBs otherwise). Returns { ok, present, mimeType, base64 } or { ok, present: false } if the requested media isn't attached to this entry.

Run the local Windy Doctor check battery and return a structured report: overall health (healthy / degraded / unhealthy), per-check status (ok / warning / error / not_applicable), severity, what was found, and (for non-ok findings) an actionable remediation step that often references the specific MCP tool to call next (e.g., "install_dependency({tool: \"wtype\"})"). Covers: paste-stack tooling presence, /dev/uinput permissions, ydotoold daemon health, polkit rule installation, Python transcription engine liveness, Mutter hotkey collision. No system mutation — pure read. Use this as the starting point for any "why is paste broken / why is transcription failing" agent flow.

Real end-to-end paste injection test. Spawns a focusable Tk scratchpad target, temporarily flips Mutter's focus-new-windows policy to "strict" so the target auto-grabs focus, fires the requested paste strategy, captures what landed in the target, and returns whether the captured text matches what was sent. SAFE TO RUN — the target is a spawned scratchpad, not the user's active window; the focus-policy flip is reverted after the test. Wayland+GNOME only in v0 (the gsettings focus-policy flip is GNOME-specific). Returns the paste-strategy attempt diagnostic too.

Write text content to a file at a given path. Default: refuses to overwrite existing files (returns a 409-shaped error with the existing file size). Pass overwrite=true to replace. Creates parent directories as needed. Returns {ok, path, bytesWritten}.

Store a (source, target, sourceLang, targetLang) tuple in the TM cache. Useful when an agent has a known-good translation it wants future lookups to find without re-calling the LLM. Upserts on duplicate keys (increments the hits counter).