Skip to content
Nightly docs track main and may describe features that are not released yet. Docs for the current release (v1.63.0) are here.

Build on Neru

How to build tools on top of Neru, such as a status bar, a launcher, voice control or another program that drives the cursor. Every command a hotkey runs is also a neru command and an IPC request, so a tool can do anything a binding can, read what Neru sees, and follow what it does. Shell recipes are in Scripting. With a coding agent, the neru-build-integration skill makes the same choices, checked against your installed version. See Set up with an agent.

What you wantWhat to useWhere it is documented
Learn what the installed build acceptsneru describe --json, neru schema ipc|configneru describe, neru schema
Brief an AI agent on this buildneru agent-guideneru agent-guide
React to events from your config[hooks]Configuration reference
Run commands from a scriptThe neru CLICLI reference
Read state as JSON--json on status, query, action snap, doctor, roles and services statusCLI reference
Follow state liveneru watch, narrowed with --eventneru watch
Find elements and their hint labelsneru query hintsneru query
Move the cursor onto an elementneru action snap, aimed with --role, --text or --directionneru action snap
Supply your own targets to hints modeneru hints --targetsSupplying your own targets
Talk to the socket directlyJSON over the IPC endpointIPC protocol
Drive Neru from a Go programThe client packageGo client
Validate configs or IPC payloadsschemas/config.schema.json, schemas/ipc.schema.jsonEditor support, Schemas

A bar that runs one long-lived command can read neru watch instead of starting a process per hook. --event drops the events the bar does not need. The stream still opens with a snapshot of the whole state.

Terminal window
neru watch --event mode_enter,mode_exit

The full script, with the jq filter and an Eww example, is in Keep a status bar in sync.

neru doctor --json prints every check as one object, so a script can test the exit status and read the details from the object. The reference says what each key means.

Terminal window
neru doctor --json | jq '{healthy, config_error: .config.error, reachable: .ipc_endpoint.reachable}'

A launcher command such as a Raycast script can read neru status --json and show the mode, and whether Neru is paused. The command fails when no daemon is running.

Terminal window
neru status --json | jq -r '"\(.mode), \(if .enabled then "running" else "paused" end)"'

neru query hints --json lists the elements hints mode would label, with the label each one would get. A voice tool can read the titles out, and a companion UI can draw its own view of them. To select one, open hints mode with the same flags, then type the label into it with neru action feed --mode:

Terminal window
label=$(neru query hints --text Save --json | jq -r '.hints[0].label')
neru hints --text Save --action left_click
neru action feed --mode $(echo "$label" | fold -w1)

A label holds only while the screen does not change, and only for the same flags. The rules are under neru query.

When no hint strategy finds a control, a tool that knows its bounds can hand them to hints mode. --targets - reads the JSON from stdin, in the shape neru query hints --json prints. Each target needs x, y, width and height.

Terminal window
echo '{"hints":[{"x":100,"y":38,"width":44,"height":52,"title":"Back"}]}' \
| neru hints --targets - --action left_click

What --targets refuses and how its targets behave is under Supplying your own targets.

A Go program can import github.com/y3owk1n/neru/client instead of writing the protocol itself. It finds the endpoint the way the neru CLI does, and returns typed replies for the status, the queries and the watch stream. Every other command goes through Send, which takes the words neru takes after the command name.

Terminal window
go get github.com/y3owk1n/neru/client

It needs Go 1.27, the version Neru’s go.mod declares, and a daemon from the release that added the package or later. An older daemon refuses its requests.

package main
import (
"context"
"errors"
"fmt"
"log"
"time"
"github.com/y3owk1n/neru/client"
)
func main() {
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
neru := client.New()
status, err := neru.Status(ctx)
if errors.Is(err, client.ErrNoDaemon) {
log.Fatal("neru is not running, start it with neru launch")
}
if err != nil {
log.Fatal(err)
}
fmt.Println("mode:", status.Mode)
// Commands without a method of their own go through Send.
_, err = neru.Send(ctx, "hints", "--action", "left_click")
var refusal *client.Error
if errors.As(err, &refusal) {
log.Fatalf("neru refused: %s", refusal.Code) // such as ERR_MODE_DISABLED
}
if err != nil {
log.Fatal(err)
}
}
  • ErrNoDaemon means nothing listens on the endpoint.
  • *client.Error is a request the daemon refused. Its Code is one of the response codes.

Watch calls your function with each line of the stream: the snapshot it opens with, then one line per event. Name events to receive only those. It returns nil when the daemon exits, and the context’s error once the context is done.

package main
import (
"context"
"fmt"
"log"
"os"
"os/signal"
"github.com/y3owk1n/neru/client"
)
func main() {
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
defer stop()
// Print the mode now, then each time it changes.
err := client.New().Watch(ctx, func(line client.WatchLine) error {
switch {
case line.Event == "snapshot":
fmt.Println(line.Status.Mode)
case line.Event == "mode_enter":
fmt.Println(line.Mode)
case line.Event == "mode_exit" && line.Reason != "switched":
fmt.Println("idle")
}
return nil
}, "mode_enter", "mode_exit")
if err != nil && ctx.Err() == nil {
log.Fatal(err)
}
}

The package follows the protocol’s compatibility rule. It breaks only at a major Neru release, so ignore fields and events you do not know. The full API is on pkg.go.dev.