Unofficial community directory · not affiliated with MetaUnofficial · not affiliated with Meta

About this site
Muse Gadgets Hub
Browse projects

muse-client — Muse Gadget project

wong2/muse-client

Software onlyTool or SDK

Short answer

muse-client offers a TypeScript interface for Muse text conversations, streamed replies, VM lookup, token refresh, and Bluetooth pairing on macOS. Its documented scope excludes audio, attachments, conversation-history listing, separate account login, and exposing local device controls to Muse.
SourcesREADME.md, Intro (opens in a new tab)README.md, API (opens in a new tab)Checked
View on GitHub (opens an external page)

What you need

Requires Node.js 22.18 or later. Bluetooth pairing requires macOS, Xcode Command Line Tools, Bluetooth access, a personal SDK token, and Developer mode in the Muse phone app. Chat can also run on Linux; a separate microcontroller board is unnecessary.

SourcesREADME.md, Intro (opens in a new tab)README.md, Pair with Muse (opens in a new tab)Checked

How you build and install it

Install the package with npm for application use. The repository CLI uses Bun to install dependencies and run pairing, followed by confirmation in the phone app. Pairing stores credentials locally. Applications connect, subscribe to events, and send messages through the SDK, saving refreshed credentials themselves; reconnecting and retrying messages are application responsibilities.

SourcesREADME.md, Install / Pair with Muse (opens in a new tab)README.md, Pair with Muse (opens in a new tab)README.md, SDK usage (opens in a new tab)Checked

How it fits

License

Apache-2.0, with LICENSE and NOTICE in the repository. The author states that the project is unaffiliated with Meta; access to Muse remains subject to the Gadget SDK Terms.

SourceREADME.md, License (opens in a new tab)Checked

Activity

Last pushed 3 Oct 2026, with 0 stars and 0 forks. This is repository activity metadata, not a build or device validation.

SourceOfficial source (opens in a new tab)Checked

Good to know

  • Audio, attachments, history listing and independent account login are not supported. The SDK does not expose local shell commands or device controls to Muse.

    SourceREADME.md (opens in a new tab)Checked

  • The optional upstream interoperability test is skipped unless MUSE_GADGET_SDK and MUSE_TEST_PYTHON are set.

    SourceREADME.md (opens in a new tab)Checked

Next steps

Source: GitHub README

README from the repository

View on GitHub (opens an external page)
License: Apache-2.0README.md at 89a3feaFetched

Written by the project’s authors, not by Muse Gadgets Hub. Shown with the images and links the authors published, under the project’s Apache-2.0 license.

muse-client

Unofficial TypeScript SDK for chatting with Muse, based on the Muse Gadget SDK protocol. Supports streaming text chat, VM lookup, token refresh, and macOS Bluetooth pairing.

Requires Node.js 22.18 or later. Pairing supports macOS; chat also runs on Linux.

Install

npm install muse-client

Pair with Muse

Pairing requires Xcode Command Line Tools (xcode-select --install) and a personal SDK token.

From the project directory:

bun install
bun run cli pair
  1. Paste your SDK token when prompted and allow Bluetooth access.
  2. In the Muse phone app, enable Settings > Devices > Developer mode, then choose Add Device.
  3. Select the printed MuseGadgetXXXXXX name, confirm, and choose Use current connection for Wi-Fi.
  4. Wait for Paired successfully.

The phone must be able to reach hatch-api.meta.ai to obtain device credentials. If pairing fails after selecting a network, check the phone's network or proxy rules.

For pairing from your own application:

import { pairMacOS } from 'muse-client/pairing';

const credentials = await pairMacOS({
  sdkToken: process.env.MUSE_SDK_TOKEN,
  onProgress: console.log,
});

Pairing saves credentials locally. The default directory is ~/Library/Application Support/MuseGadgetPair/ on macOS and /var/lib/musegadget/ on Linux. Use --credentials <directory> in the CLI or directory in pairMacOS to choose another location. Existing pairings are preserved.

CLI example

The CLI runs from the repository:

bun run cli chat                 # Interactive chat; /quit or Ctrl+C to exit
bun run cli vms                  # List Muse VMs
bun run cli check                # Check the connection without sending a message
bun run cli send "Hello Muse"    # Send a message and print its acknowledgement
bun run cli watch --json         # Stream chat events
bun run cli unpair               # Remove local pairing credentials

Use --vm <id> to choose a VM, --session <id> for an existing side chat, and --help for all options.

Before running unpair, stop any chat or pairing process. It preserves the device identity and SDK token. To remove the device association from Muse, use Settings > Devices in the phone app.

Show the full READMEShow less

SDK usage

After pairing:

import { MuseClient } from 'muse-client';
import { loadCredentials, saveCredentials } from 'muse-client/credentials';

const client = await MuseClient.connect({
  credentials: await loadCredentials(),
  onCredentials: saveCredentials,
});

try {
  const events = await client.subscribe();
  const reading = (async () => {
    for await (const event of events) {
      if (event.event === 'delta.text_append') {
        process.stdout.write(String(event.payload.text ?? ''));
      }
    }
  })();
  reading.catch(() => {}); // Handle early rejection while sendMessage is pending.

  const ack = await client.sendMessage('Hello!');
  console.log('Accepted message:', ack.messageId);
  await reading; // Streams until closed or aborted.
} finally {
  client.close();
}
  • Subscriptions default to the main chat. For an existing side chat, pass the same sessionId to subscribe and sendMessage. A new side chat must be created by sending its first message before subscribing.
  • Events may include activity from other clients in the same session. Message completion does not necessarily mean the whole assistant turn has ended.
  • Persist refreshed credentials with onCredentials. Avoid concurrent processes sharing the same credentials. The SDK does not automatically reconnect or resend.

API

Import Exports
muse-client MuseClient, MuseAccount
muse-client/credentials loadCredentials, saveCredentials, unpair
muse-client/pairing pairMacOS, buildPairingHelper, validateSDKToken

MuseClient provides connect, sendMessage, subscribe, and close. MuseAccount provides listVMs and refresh.

Audio, attachments, history listing, and independent account login are not supported. The SDK does not expose local shell commands or device controls to Muse.

Development

bun run typecheck
bun run test
bun run build

The optional upstream interoperability test requires MUSE_GADGET_SDK and MUSE_TEST_PYTHON; it is skipped when these are unset.

License

Apache-2.0; see LICENSE and NOTICE. This project is unofficial and is not affiliated with Meta. Muse service access is subject to the Gadget SDK Terms.

More projects

All projects

hackshop-mcp

msanchezgrice/hackshop-mcp

Hardware-literate AI scout for tinkerers. Idea-to-hardware mapping via MCP.

Software onlyTool or SDK
0 starsMITPushed
Featured

muse-r1

cameronapak/muse-r1

Native Android HOME app that turns a Rabbit r1 running LineageOS into a Muse gadget.

Rabbit r1Audio
1 starsMITPushed
Featured

muse-pocket

viticci/muse-pocket

An e-paper Muse companion for the Xteink X4 Pro: character, status, settings and recoverable SD firmware updates.

Xteink X4 ProDisplay
22 starsApache-2.0Pushed