Socket & Protocol

Socket location

By default, the IPC socket is at:

/tmp/tarmac-$USER.sock

For example, /tmp/tarmac-alice.sock.

Override with the TARMAC_SOCKET environment variable:

TARMAC_SOCKET=/tmp/my-tarmac.sock tarmac

The socket is created with mode 0600 (owner read/write only). Only the user who started tarmac can connect to it.

The protocol is line-based JSON. Each request and response is a single JSON object terminated by a newline (\n).

{"command": "focus", "args": ["left"]}

Field	Type	Required	Description
`command`	string	yes	The command name
`args`	string[]	no	Command arguments (defaults to `[]`)

{"success": true, "data": {...}, "error": null}

Field	Type	Description
`success`	bool	Whether the command succeeded
`data`	any/null	Response data (for query commands)
`error`	string/null	Error message if `success` is false

Successful command:

→ {"command":"workspace","args":["3"]}
← {"success":true}

Query with data:

→ {"command":"get-focused","args":[]}
← {"success":true,"data":{"window_id":1234,"app_name":"Firefox","title":"Home"}}

Error:

→ {"command":"invalid","args":[]}
← {"success":false,"error":"unknown command: invalid"}

You can interact with the socket directly using socat or nc:

echo '{"command":"get-workspaces","args":[]}' | socat - UNIX-CONNECT:/tmp/tarmac-$USER.sock

Or keep a connection open for multiple commands:

socat READLINE UNIX-CONNECT:/tmp/tarmac-$USER.sock

Then type JSON requests interactively.

If a command doesn't complete within 5 seconds, the IPC server returns a timeout error:

{"success": false, "error": "command timed out"}

This prevents stalled commands from blocking other IPC clients.

Each IPC connection can send multiple requests sequentially. The connection stays open until the client closes it or the daemon shuts down.

The one exception is the subscribe command, which switches the connection into streaming mode — see Events & Subscribe.