{"id":50583596,"url":"https://github.com/ddrayne/openclaw-modue","last_synced_at":"2026-06-05T04:05:39.222Z","repository":{"id":349139250,"uuid":"1200821352","full_name":"ddrayne/openclaw-modue","owner":"ddrayne","description":"Modue control surface plugin for OpenClaw — live agent activity, channel health, physical approve/deny buttons, and agent-callable LED/display tools.","archived":false,"fork":false,"pushed_at":"2026-05-02T21:43:13.000Z","size":225,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-02T23:30:55.536Z","etag":null,"topics":["ai-assistant","control-surface","macos","modue","modue-plugin","openclaw"],"latest_commit_sha":null,"homepage":"https://github.com/ddrayne/openclaw-modue","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ddrayne.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-03T21:38:43.000Z","updated_at":"2026-05-02T21:43:17.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ddrayne/openclaw-modue","commit_stats":null,"previous_names":["ddrayne/openclaw-modue"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ddrayne/openclaw-modue","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddrayne%2Fopenclaw-modue","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddrayne%2Fopenclaw-modue/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddrayne%2Fopenclaw-modue/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddrayne%2Fopenclaw-modue/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ddrayne","download_url":"https://codeload.github.com/ddrayne/openclaw-modue/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddrayne%2Fopenclaw-modue/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33928805,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-05T02:00:06.157Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-assistant","control-surface","macos","modue","modue-plugin","openclaw"],"created_at":"2026-06-05T04:05:38.385Z","updated_at":"2026-06-05T04:05:39.216Z","avatar_url":"https://github.com/ddrayne.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @modue/openclaw\n\nA [Modue](https://www.modue.com) control surface plugin for\n[OpenClaw](https://openclaw.ai) — turn the Modue's display, slider,\nkeys, knob, and LED cluster into a physical dashboard for your AI\nassistant.\n\nBuilt for headless setups (Mac Mini behind a TV, no monitor) where you\nwant at-a-glance status and physical approve / deny buttons for the\nagent without context-switching to a terminal.\n\n## How the pieces fit\n\n```\n   ┌─────────────────────┐                    ┌─────────────────────┐\n   │   Modue device      │                    │   OpenClaw agent    │\n   │ (display, LEDs,     │                    │ (LLM, channels,     │\n   │  slider, keys)      │                    │  approvals, etc.)   │\n   └──────────┬──────────┘                    └──────────┬──────────┘\n              │                                          │\n              ▼                                          │\n   ┌─────────────────────┐                               │\n   │  this plugin        │                               │\n   │  (@modue/openclaw)  │                               │\n   │  inside Modue app   │                               │\n   └──────────┬──────────┘                               │\n              │ WebSocket (auth + device pairing)        │\n              ▼                                          ▼\n   ┌────────────────────────────────────────────────────────────┐\n   │              OpenClaw gateway (host)                       │\n   │   relays modue.* events via the openclaw-modue-bridge      │\n   │   plugin (https://github.com/ddrayne/openclaw-modue-bridge)│\n   └────────────────────────────────────────────────────────────┘\n```\n\nYou need **both** sides — this Modue-platform plugin, and the\nopenclaw-side\n[`@ddrayne/openclaw-modue-bridge`](https://github.com/ddrayne/openclaw-modue-bridge)\nplugin that registers the `modue.*` gateway methods.\n\n## What you get on the device\n\n### Display widgets (7 total)\n\n| Widget        | Size  | Shows                                                               |\n| ------------- | ----- | ------------------------------------------------------------------- |\n| `Claw Status` | 1×1   | Compact status pill — emoji + state + elapsed timer                 |\n| `Claw Stream` | 2×2   | Mid-size live agent text + status line                              |\n| `Claw Live`   | 4×2   | Main streaming view — full agent reply, source, controls            |\n| `Claw Full`   | 8×2   | Immersive reading view — large type, optimized for far viewing      |\n| `Channels`    | 2×1   | Per-channel connection health (WhatsApp, Telegram, Slack, …)        |\n| `Approval`    | 2×1   | Pending exec-approval card with risk level + key hint               |\n| `Claw Info`   | 2×2   | Context-aware: scroll position, model name, today's cost, approval  |\n\nDrag the widgets you want into your Modue layout in the Modue app.\n\n### Physical controls\n\n- **Left key**: approve pending exec / abort current generation / wake the\n  assistant (depending on context).\n- **Right key**: deny pending exec / fetch a usage-cost summary onto the\n  display (depending on context).\n- **Center key**: fetch + render the current channel-connection status.\n- **Slider** (motorized fader): scroll back through the streaming reply\n  text. Auto-resets to live after 5s of no movement. Agents can also push\n  a target position via the `modue_slider` tool.\n- **Knob**: reserved.\n- **LED cluster**: ambient status — green=idle, purple=thinking,\n  blue=replying, orange=working, red=error, gray=offline. Flashing amber\n  during a pending approval. Agents can override patterns through the\n  `modue_leds` tool.\n\n## Setup\n\n### Prerequisites\n\n- A [Modue](https://www.modue.com) device + the Modue desktop app (macOS).\n- An [OpenClaw](https://openclaw.ai) install with the gateway running\n  locally — `openclaw gateway status` should report `Runtime: running`.\n- The companion openclaw-side plugin\n  [`@ddrayne/openclaw-modue-bridge`](https://github.com/ddrayne/openclaw-modue-bridge)\n  installed (`openclaw plugins install @ddrayne/openclaw-modue-bridge`).\n\n### Install (Modue side)\n\n```sh\ngit clone https://github.com/ddrayne/openclaw-modue.git\nln -s \"$PWD/openclaw-modue\" \"$HOME/Library/Application Support/modue/plugins/openclaw-modue\"\n```\n\nThen in the Modue app: relaunch (or `Cmd+Shift+R` to hot-reload). The\nplugin appears under **Plugins → OpenClaw**.\n\n### Configure\n\n1. Pull your gateway auth token from OpenClaw:\n\n   ```sh\n   python3 -c \"import json,os; print(json.load(open(f'{os.path.expanduser(\\\"~\\\")}/.openclaw/openclaw.json'))['gateway']['auth']['token'])\"\n   ```\n\n2. In the Modue plugin settings, set:\n   - **Gateway URL**: `ws://127.0.0.1:18789` (default — leave alone unless\n     you've moved the gateway).\n   - **Gateway Token**: the value you pulled in step 1.\n\n3. Click **Connect**, or `Cmd+Shift+R` to reload.\n\n### Verify\n\nTail the plugin log:\n\n```sh\ntail -f \"$HOME/Library/Application Support/modue/pluginLogs/openclaw.log\"\n```\n\nYou should see, in order:\n\n```\nConnecting to OpenClaw at ws://127.0.0.1:18789\nChallenge received, building device identity\nDevice identity loaded: …\nDevice token saved (pairing approved)        ← first time only\nConnected to OpenClaw gateway\nmodue bridge primed\n```\n\nDrag a widget (e.g. `Claw Live`) onto the device. Send any message\nthrough OpenClaw and the agent's reply should stream onto the display\nin real time.\n\n## Repo layout\n\n```\nopenclaw-modue/\n├── index.js           # Entry — registers config, widgets, slider, keys, LEDs\n├── lib/\n│   ├── connection.js  # Singleton — agent state, subscriber pattern, lifecycle\n│   ├── widgets.js     # 7 display widgets (Claw Status / Stream / Live / …)\n│   ├── ws-client.js   # Minimal WS client (Node http + crypto, no npm deps)\n│   └── renderer.js    # Display formatting helpers (colors, truncate, time)\n├── test/\n│   ├── connection.test.js  # 153 cases, exhaustive Connection coverage\n│   └── ws-client.test.js   # 4 cases for the disconnect-drain behavior\n├── icon.png / icon.svg\n├── package.json\n├── sync.sh            # Dev: rsync source -\u003e Modue install dir\n└── README.md\n```\n\nZero npm dependencies. The plugin uses Node 22+ built-ins only (`http`,\n`crypto`, `events`).\n\n## Development\n\n```sh\nnpm test                           # 157 tests, ~250ms\n\n# Push local source into the Modue install dir without committing:\nbash sync.sh\n# Then Cmd+Shift+R in Modue.\n```\n\n`\"devMode\": true` is set in `package.json` so the Modue app picks up\nhot-reloads.\n\n## Troubleshooting\n\n**`gateway token mismatch`**\n\nModue's stored `Gateway Token` doesn't match `gateway.auth.token` in\n`~/.openclaw/openclaw.json`. The token rotates if you reinstall or\nupgrade OpenClaw. Re-extract (see Configure step 1) and paste the new\nvalue.\n\n**`bridge ping failed: …`**\n\nThe openclaw-side\n[`@ddrayne/openclaw-modue-bridge`](https://github.com/ddrayne/openclaw-modue-bridge)\nplugin isn't loaded. Install it and restart the gateway:\n\n```sh\nopenclaw plugins install @ddrayne/openclaw-modue-bridge\nopenclaw gateway stop \u0026\u0026 openclaw gateway start\n```\n\n**Modue plugin process RSS climbing during agent activity**\n\nYou're on an old version. Update to the latest commit (the per-notify\n`channels.status` fan-out used to OOM the Modue platform under sustained\nstreaming). `Cmd+Shift+R` after pulling.\n\n**Plugin log shows multiple parallel \"Attempting reconnect…\"**\n\nThe Connect button or widget initializers fired more than once. Harmless\nonce auth succeeds, but worth `Cmd+Shift+R` to get a clean single\nconnection.\n\n## Compatibility\n\n- Node **22+** required (uses built-in WebSocket framing patterns).\n- macOS only (`os: \"darwin\"` in package.json — Modue itself is macOS only).\n- OpenClaw protocol v3 (PROTOCOL_VERSION constant in `lib/ws-client.js`).\n\n## License\n\nISC.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fddrayne%2Fopenclaw-modue","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fddrayne%2Fopenclaw-modue","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fddrayne%2Fopenclaw-modue/lists"}