Katie GUI

An Electron desktop client for the Katie WebSocket API.

Configuration

Create .env in the project root:

KATIE_WS_URL=ws://shamu.network.orcachill.in:3000/ws
KATIE_WS_TOKEN=replace-with-the-server-token
KATIE_CLIENT_ID=katie-gui

The URL defaults to ws://shamu.network.orcachill.in:3000/ws and the client ID defaults to katie-gui. KATIE_WS_TOKEN is required and must match WS_TOKEN on the Katie server.

The token stays in Electron's main process and is sent in the Authorization header. It is not bundled into renderer assets.

KATIE_CLIENT_ID identifies both the persistent conversation and the Katie permission identity. Keep it stable to preserve conversation context.

Hover over the overlay to reveal the settings button. Settings can change the pinned screen corner, PipeWire input, WebSocket URL, token, and client ID. They are stored in Electron's user-data directory and override .env defaults.

Run

npm install
npm start

For source watches and Electron development tools:

npm run dev

Click the red record button to start listening. Each utterance is sent as a 16 kHz mono WAV after 700 ms of silence; click the button again to stop. Voice capture requires PipeWire's pw-record command. Set MIC_SOURCE in .env to override the default PipeWire input.

Server

The Katie instance must enable its WebSocket adapter:

WS_ADAPTER=1
WS_TOKEN=replace-with-the-server-token

Restart Katie after changing these values. If the endpoint is later served over TLS, change KATIE_WS_URL from ws:// to wss://.