hx-remote | hxr

hx-remote is a small Unix-only bridge for opening files in an already-running Helix session. It uses a Unix-domain socket for local commands and Helix's LSP window/showDocument support to open and focus files.

The installed executable is named hxr:

hxr --listen
hxr --status
hxr --open src/main.rs Cargo.toml
hxr --open src/main.rs:50:12
hxr --stop
git diff | hxr --stdin-name changes.diff --open -

Install

Helix 24.03 or newer is required.

cargo install hx-remote

Add this once to ~/.config/helix/languages.toml (or print the snippet with hxr --print-config; a copy is also in examples/helix/languages.toml):

[language-server.hx-remote]
command = "hxr"
args = ["--lsp"]

[[language]]
name = "hx-remote"
scope = "source.hx-remote"
file-types = ["hxremote"]
language-servers = ["hx-remote"]

You can check that Helix sees the executable with:

hx --health hx-remote

Use

Start the receiving Helix instance from the directory you want to use as its workspace:

hxr --listen

This creates and opens a small sentinel file under the user cache directory. Keep that buffer open: its language server is the bridge. From another process, shell, or file explorer, run:

hxr --open /absolute/path/to/file

Relative paths are resolved by the sending hxr process, so file explorers may pass either relative or absolute paths. Several files may be sent in one call; Helix focuses the last one.

Positions use one-based line and column numbers:

hxr --open src/main.rs:50
hxr --open src/main.rs:50:12

To open piped text, use -. The bridge keeps a temporary file alive for the rest of the Helix session. --stdin-name supplies an extension for syntax detection:

git diff | hxr --stdin-name working-tree.diff --open -

The default socket is $XDG_RUNTIME_DIR/hx-remote.sock when that directory is available, otherwise a per-user socket in the system temporary directory. Set HXR_SOCKET or pass --socket PATH to run independent Helix listeners:

HXR_SOCKET=/tmp/project-a.sock hxr --listen
HXR_SOCKET=/tmp/project-a.sock hxr --open src/lib.rs

Extra Helix arguments can be supplied by repeating --helix-arg:

hxr --helix-arg=-w --helix-arg=/tmp/helix-working-directory --listen

Check whether the selected socket is open and accepting connections with:

hxr --status

The command exits successfully while a listener is present and unsuccessfully otherwise. Stop the bridge sidecar gracefully with hxr --stop. If it is not responding normally, hxr --stop --force terminates it immediately. Both commands affect only the server selected by --socket or HXR_SOCKET; they do not close Helix itself.

How it works

Helix starts hxr --lsp for the .hxremote sentinel buffer. That process performs the minimal LSP initialization handshake and listens on a local Unix socket. hxr --open sends a path to the socket, and the sidecar emits a window/showDocument request with takeFocus = true. The socket is permissioned to the current user (0600) and stale socket files are removed safely at startup.