IPC

fht-compositor features a inter-process communication system allowing you fetch data from the compositor and modify the live compositor state.

You can communicate with this IPC with one of:

1. fht-compositor ipc subcommand in the CLI, fht-compositor ipc --help for more information

NOTE

Version mismatches between the compositor and the CLI may cause errors parsing, so when updating make sure to restart your session to make sure both the CLI and compositor are up-to-date.

fht-compositor ipc version prints both versions, you can use it to check for mismatches.

$ fht-compositor ipc version
# Here, both the versions are matching, no need to restart
Compositor: 25.03.1 (a17380aa)
CLI: 25.03.1 (a17380aa)

2. Programmatic access to the IPC, through its Unix socket, useful for scripting or integrating with other parts of your system:
   • If you are using Rust, use the fht-compositor-ipc library directly, as it has all the IPC types pre-defined with (De)Serialize.
   • You can do shell scripting using socat, though you'll have to figure out what to write inside the socket yourself.

TIP

To see how the requests/responses are formatted, you can setup and temporary socket and link it with the real one using socat.

socat -v UNIX-LISTEN:~/temp.sock,fork UNIX-CONNECT:${FHTC_SOCKET_PATH}
# Then, in another terminal, you can connect to ~/temp.sock
FHTC_SOCKET_PATH=~/temp.sock fht-compositor ipc version

You can also use fht-compositor ipc --json to see JSON-formatted responses if you only care about that.

State updates

As of right now, the IPC doesn't support sending live events and updates to the clients, so you will have to resort to polling every few seconds.

; Here, we store the space data into a global variable, updated each second.
; Since eww supports native JSON decoding, this is really handy
(defpoll space-data :interval "1s"
                    ; Initital value is empty, to make eww startup fast
                    :initial "{\"monitors\": {}, \"primary-idx\": -1, \"active-idx\": -1}"
                    `fht-compositor ipc --json space`)

; Now, somewhere else, you can immediatly use the data to your liking
(label :text "Output: ${space-data.monitors[0].name}")