DesktopClaw

A small Windows desktop avatar that gives OpenClaw a visible, voice-enabled presence.
Read the release notes »

Download Releases · Report Bug · Request Feature

DesktopClaw is a transparent Electron desktop companion for OpenClaw. It sits on your Windows desktop as a small animated avatar, gives OpenClaw a visible presence, speaks useful responses back through local text-to-speech, and keeps request state clear while work is still running.

The goal is to make OpenClaw feel less like a background service and more like a present, responsive assistant. You can send a chat request, check gateway settings, change app options, or use the tray while the request continues. DesktopClaw keeps the active request alive and only removes the in-progress indicator when that specific request has a valid response.

What it does today:

• Connects to OpenClaw through a WebSocket gateway.
• Shows a draggable, transparent, always-on-top desktop avatar.
• Accepts typed prompts and push-to-talk voice input.
• Speaks responses with local Piper text-to-speech.
• Streams OpenClaw run progress into request-scoped thought bubbles.
• Handles long-lived OpenClaw sessions with interleaved user, tool, retry, and assistant messages.
• Lets you double-click the avatar to interrupt speech.
• Offers gateway status, model refresh, mute, visibility, settings, history, diagnostics, and quit actions from the system tray.
• Uses idle action sprites so the avatar can read, sleep, or work on a laptop when not actively busy.
• Supports optional idle click-through behavior.

(back to top)

• 
• 
• 
• Piper TTS
• Vosk
• OpenClaw

(back to top)

Installer and standalone builds are available from the GitHub releases page:

Use the installer when you want DesktopClaw registered like a normal Windows app with shortcuts. Use the standalone/portable build when you want to try it without installing it system-wide.

Runtime settings are stored under the current Windows user profile, so packaged builds can preserve your gateway, voice, hotkey, and UI preferences between launches.

(back to top)

Use the release installer or standalone build for normal use. Run from source when you are developing, testing local gateway behavior, or changing the avatar code.

• Windows.
• Node.js 20.x or newer compatible with the Electron dependency set.
• An OpenClaw gateway reachable over WebSocket.
• Optional: Piper installed locally for speech output.
• Optional: Vosk model files under models/ for native speech capture.

git clone https://github.com/divbasson/DesktopClaw.git
cd DesktopClaw
npm install
npm start

The app starts as a transparent desktop avatar. Hover or click the avatar to open the text input, or use the listen hotkey for voice input.

(back to top)

DesktopClaw is designed to feel like a small companion rather than a static chat window.

• Click or hover near the avatar to bring up the text input.
• Type a request and press Enter.
• Use Ctrl+Shift+Space to bring DesktopClaw forward and focus the text box.
• Watch compact thought-bubble request indicators while OpenClaw is working.
• Continue using settings or the tray while a request is in progress.
• Double-click the avatar while it is speaking to stop the current spoken response.
• Use the tray menu for mute, visibility, settings, status checks, and model refresh.
• Leave it idle and the avatar will occasionally read, sleep, or work on a laptop.

Default hotkeys:

• Focus text input: Ctrl+Shift+Space
• Mute: Ctrl+Shift+M
• Show/hide: Ctrl+Shift+H
• Settings: Ctrl+Shift+S

(back to top)

DesktopClaw is primarily a WebSocket gateway client. The default settings point at a local OpenClaw gateway:

{
  "gateway": {
    "mode": "gateway",
    "baseUrl": "ws://localhost:18789",
    "eventsUrl": "ws://localhost:18789",
    "sessionKey": "main",
    "timeoutMs": 30000
  }
}

The app talks to OpenClaw through gateway methods such as:

• connect
• chat.send
• chat.history
• health / status
• sessions.list
• models.list

OpenClaw sessions are long-lived and can contain messages from the desktop app, other chat surfaces, tool calls, retries, model errors, and final assistant replies. DesktopClaw correlates replies to the matching user request instead of assuming the whole session represents one job.

During an active request, DesktopClaw forwards OpenClaw run milestones to the renderer so the request indicator can show meaningful progress instead of a generic spinner. Late run events are ignored after a request reaches a terminal state, which prevents completed jobs from reappearing as active.

Model listing is supported through OpenClaw. Session model switching depends on backend support and may be unavailable on some gateway versions.

(back to top)

DesktopClaw supports native voice input and local speech output:

• Voice input uses the native Vosk listener in src/native/vosk_listener.py.
• The global shortcut focuses the text input for fast typed interaction.
• Text-to-speech uses Piper when tts.usePiperTts is enabled.
• The default Piper voice path is configured as tts.piperModel.
• Double-click the avatar while it is speaking to stop the current spoken response.
• Emoji and pictographic symbols are stripped from the TTS path so they remain visible in the reply bubble without being spoken aloud.

Default Piper settings:

{
  "tts": {
    "usePiperTts": true,
    "piperExe": "C:\\piper\\piper\\piper.exe",
    "piperModel": "F:\\DesktopClaw\\models\\piper\\voices\\cori-med.onnx"
  }
}

(back to top)

Default settings live in:

settings.defaults.json

Runtime settings are written by Electron under the current user's app data folder:

%APPDATA%\desktopclaw\settings.json

The settings panel can update gateway connection details, token/password values, hotkeys, click-through behavior, voice settings, and status polling options.

(back to top)

For an unpacked Windows build:

npm run dist:dir

For installer and portable artifacts:

npm run dist

Build output is written to dist/. Release artifacts include an installer and a standalone/portable build when produced through the Windows packaging flow.

(back to top)

• Transparent desktop avatar shell.
• WebSocket OpenClaw gateway client.
• Native Vosk push-to-talk capture.
• Piper text-to-speech playback.
• Request-scoped thought-bubble job indicators.
• Speech interruption by double-clicking the avatar.
• OpenClaw run-progress streaming into the renderer.
• Mood/presence styling for listening, thinking, speaking, success, and error states.
• Idle action sprites for reading, sleeping, and laptop work.
• Tray history and diagnostics panels.
• Stronger packaged-app smoke tests for installer and standalone artifacts.
• Deeper visual QA around transparent-window edge cases.
• More polished first-run gateway pairing flow.
• Better in-app model/backend capability messaging.

See the open issues for tracked bugs and feature requests.

(back to top)

Issues and pull requests are welcome. For useful reports, include:

• DesktopClaw version or commit.
• Whether you used the installer, standalone build, or source checkout.
• OpenClaw gateway URL/mode, with secrets removed.
• Relevant lines from %APPDATA%\desktopclaw\logs\desktopclaw-debug.log.
• A short description of what you expected and what happened.

Please keep changes focused and verify behavior against a real OpenClaw gateway when the change touches messaging, sessions, voice, or packaging.

(back to top)

Distributed under the MIT license declared in package.json.

(back to top)

src/
  main/
    app-controller.js    Main orchestration and IPC
    config-store.js      Runtime config lifecycle
    logger.js            App log writer
    main.js              Electron entrypoint
    native-stt.js        Native Vosk speech capture wrapper
    native-tts.js        Piper synthesis wrapper
    openclaw-client.js   OpenClaw WebSocket gateway client
    preload.js           Safe renderer bridge
    shortcut-manager.js  Global hotkeys
    tray-manager.js      System tray menu
    ui-shell.js          Transparent Electron window
  renderer/
    animation_engine.js  Avatar animation state
    index.html           Avatar UI root
    openclaw_client.js   Renderer gateway adapter
    renderer.js          Avatar behavior composition
    styles.css           Visual styling and animation states
    tts_engine.js        Renderer speech playback controller
    ui_shell.js          Bubble/settings helpers
    wake_word.js         Wake/listen flow support
  shared/
    config.js            Config load/save helpers

• Keep request UI scoped to individual requests. Do not use OpenClaw session lifetime to decide whether a request indicator should remain visible.
• Do not let progress events move a terminal request back into a working state.
• OpenClaw may write transient assistant errors before a valid retry response. The client should prefer the first usable assistant text that follows the matching user message.
• Settings changes should not close a gateway client that is still waiting for an active chat response.
• The transparent window is sensitive to blurred layers near its edges; avoid large blurred rectangles that can reveal window bounds.
• Idle action sprites should preserve the same visual scale and alpha baseline as openclaw_agent_sprite.png.
• The TTS path should clean screen-only symbols such as emoji without changing the visible response bubble.
• npm run lint is currently a placeholder script, so syntax checks and live gateway tests are still important.

_{DesktopClaw - an OpenClaw desktop companion}