Toak/docs/PROTOCOL.md

Daemon Socket Protocol

Toak uses a lightweight, custom Unix Domain Socket protocol for IPC (Inter-Process Communication). This allows front-end short-lived CLI tools (like toak toggle) to execute instantly while the persistent state and API operations happen inside the background daemon (toak daemon).

Connection

The UNIX domain socket is typically located at: $XDG_RUNTIME_DIR/toak.sock (falls back to /tmp/toak.sock if $XDG_RUNTIME_DIR is not set).

Message Format

Clients send small byte arrays to issue commands to the server. Depending on the command, the structure ranges from a single byte to a 3-byte payload containing the command ID and configuration flags for standard output handling.

Command Bytes

Command	Byte	Description
START	1	Forces the daemon to start recording. Ignored if already recording.
STOP	2	Forces the daemon to stop recording and begin processing the audio. Takes flags for response handling.
ABORT	3	Stops audio recording and discards the buffer without making API calls.
TOGGLE	4	Stops recording if currently recording; starts recording if currently inactive. Takes flags for response handling.

Payload Formats

1-Byte Payloads (START, ABORT)

When the client only needs to trigger state changes without receiving processing results back, it sends a single byte.

[ Command Byte ]

Example (ABORT): [ 0x03 ]

3-Byte Payloads (STOP, TOGGLE)

When asking the daemon to process audio, the client can specify how it wants to receive the finalized text: typed via hotkeys (default), piped to standard output (--pipe), or copied to the clipboard (--copy).

The client sends exactly 3 bytes:

[ Command Byte ] [ Pipe Flag ] [ Copy Flag ]

• Byte 0: The command (0x02 or 0x04)
• Byte 1: Pipe to Stdout: 0x01 if enabled, 0x00 if disabled.
• Byte 2: Copy to Clipboard: 0x01 if enabled, 0x00 if disabled.

Example (TOGGLE with stdout piping enabled): [ 0x04, 0x01, 0x00 ]

Server Responses

Depending on the flags provided in a 3-Byte Payload:

1. Default (No flags set): The server will process the audio, handle LLM modifications, and inject the text into the user's active window using Wayland (wtype) or X11 (xdotool). The socket is closed by the server.

2. Pipe or Copy Flag Set: The client will keep the connection open and wait to read the incoming text from the server. The server will stream UTF-8 encoded text chunks back to the client as the LLM generates them. The client reads these chunks and pushes them to stdout. Once sending is complete, the server closes the socket.