Agent Events

Nexion publishes the state of every agent running in its panes as events on the nexion CLI event stream, and focuses any pane by id. Use them to notify, automate or build a status view without polling.

Requires build 4548 or later. Covers every window and space, including herdr and herdr-core panes.

Overview

  • • agent.state-changed: sent when a pane's agent changes state.
  • • pane.focused: sent when the focused pane changes.
  • • pane focus --pane-id: focuses a pane in any window, space or tab.
  • • Metadata only: events never contain terminal output or agent messages.

Subscribing

One JSON-RPC notification per line, from every window and space. On subscribe, one event is sent for each running agent with previous: null. The stream ends when Nexion quits; subscribe again after it restarts.

nexion event
$ nexion event subscribe --all-windows "agent.*"
$ nexion event subscribe --all-windows "pane.*"
$ nexion event subscribe "agent.*" | jq -c ".params"
agent.state-changed
{"jsonrpc":"2.0","method":"agent.state-changed","params":{
  "at":"2026-11-13T11:42:05.123Z",
  "windowId":"8066A198-…","spaceId":"49F65553-…","tabId":"4D3ADABB-…","paneId":"78DBA605-…",
  "agent":"claude","state":"waiting","previous":"working","reason":"question",
  "cwd":"/Users/you/code/app","title":"Claude Code","projectName":"app","focused":false}}
Field Meaning
stateworking, idle, waiting (waiting for user input) or exited. The same values nexion pane list reports as agentState.
previousPrevious state. null in the initial events and when an agent starts.
reasonfinished, question, permission, error, exited or null. Provided by Claude Code hooks; usually null for other agents.
agentclaude, codex, opencode, gemini, or another recognised agent.
paneId, tabId, windowId, spaceIdIds of the pane and its location. paneId is the id printed by pane list and accepted by pane focus --pane-id.
cwd, projectNameWorking directory of the pane, and the tab name shown in the sidebar.
titleTerminal title set by the program (Claude Code writes a short topic).
focusedtrue when the pane is focused in the key window and Nexion is the active app.
atTimestamp, ISO 8601, UTC.

Events are sent only on a state change. exited is sent about 3 seconds after the agent process ends, or immediately when its pane closes.

Jumping to a Pane

pane.focused carries at, paneId, tabId, windowId and spaceId. It is sent when the focused pane changes and when Nexion becomes the active app.

nexion pane focus
$ nexion pane focus --pane-id 78DBA605-3558-4AFB-9C8F-B109321400A0
$ nexion pane focus --pane-id reviewer    # agent name or pane label

Activates Nexion, raises the pane's window, switches to its space and tab, removes any zoom and focuses the pane. Accepts a pane id, an agent name or a pane label. Exits with a non-zero status if the pane does not exist. When called from inside a Nexion pane while another app is active, the pane is selected but Nexion is not activated.

Recipes

bash and jq, both included with macOS. The long-running scripts reconnect after Nexion restarts; run them from a LaunchAgent or a pane.

Phone notifications

Sends an ntfy notification when an agent finishes or waits for input, unless its pane is focused. Use a topic name that cannot be guessed, or a self-hosted ntfy server.

agents-to-phone.sh
#!/bin/bash
# Sends an ntfy notification when an agent finishes a turn or waits for
# input, unless its pane is focused.
#   NTFY_URL=https://ntfy.sh/<your-secret-topic> ./agents-to-phone.sh
NEXION="${NEXION_CLI:-nexion}"
: "${NTFY_URL:?set NTFY_URL, e.g. https://ntfy.sh/<your-secret-topic>}"
while true; do
  "$NEXION" event subscribe 'agent.*' |
    jq -c --unbuffered '.params | select(.previous != null and .focused == false)
      | select(.state == "waiting" or (.state == "idle" and .reason == "finished"))' |
    while read -r e; do
      agent=$(jq -r '.agent // "agent"' <<<"$e")
      where=$(jq -r '.projectName // .cwd // ""' <<<"$e")
      case $(jq -r '.reason // .state' <<<"$e") in
        finished)   msg="$agent finished" ;;
        question)   msg="$agent has a question" ;;
        permission) msg="$agent needs a permission" ;;
        *)          msg="$agent is waiting for you" ;;
      esac
      curl -s -H "Title: Nexion" -d "$msg in $where" "$NTFY_URL" >/dev/null
    done
  sleep 5   # Stream ended (Nexion quit or not running): subscribe again
done

Command on finish

Runs a command in the agent's working directory when it finishes a turn. Default: git diff --stat; set ON_FINISH to change it.

on-finish.sh
#!/bin/bash
# Runs ON_FINISH in the agent's working directory after each finished turn.
#   ON_FINISH='git diff --stat' ./on-finish.sh
NEXION="${NEXION_CLI:-nexion}"
ON_FINISH="${ON_FINISH:-git diff --stat}"
while true; do
  "$NEXION" event subscribe 'agent.*' |
    jq -r --unbuffered '.params | select(.previous == "working" and .state == "idle" and .reason == "finished") | .cwd' |
    while read -r dir; do
      [ -d "$dir" ] || continue
      echo "── $(date +%H:%M:%S) finished in $dir"
      (cd "$dir" && eval "$ON_FINISH")
    done
  sleep 5
done

Focus mode while agents work

Runs the Shortcut "Agents On" when the first agent starts working and "Agents Off" when none is working. Create both Shortcuts with the Set Focus action, or set FOCUS_ON and FOCUS_OFF to other commands.

focus-while-working.sh
#!/bin/bash
# Runs FOCUS_ON when the first agent starts working and FOCUS_OFF when no
# agent is working. Defaults: the Shortcuts "Agents On" and "Agents Off".
# Written for bash 3.2 (the macOS default): no associative arrays.
NEXION="${NEXION_CLI:-nexion}"
ON="${FOCUS_ON:-shortcuts run 'Agents On'}"
OFF="${FOCUS_OFF:-shortcuts run 'Agents Off'}"
while true; do
  "$NEXION" event subscribe 'agent.*' |
    jq -r --unbuffered '.params | "\(.paneId) \(.state)"' |
    { working=" "; was=0
      while read -r pane state; do
        working="${working// $pane / }"
        [ "$state" = working ] && working="$working$pane "
        if [ "$working" != " " ]; then now=1; else now=0; fi
        if [ $now != $was ]; then
          if [ $now = 1 ]; then eval "$ON"; else eval "$OFF"; fi
          was=$now
        fi
      done
      [ $was = 1 ] && eval "$OFF"   # Stream ended: no agent is working
    }
  sleep 5
done

Focus the waiting agent

Focuses the first agent in waiting state, otherwise the first one with an unseen finished turn. Bind it to a hotkey (Raycast, BetterTouchTool, Stream Deck).

jump-to-agent.sh
#!/bin/bash
# Focuses the first agent in waiting state, otherwise the first one with an
# unseen finished turn. Meant for a hotkey.
NEXION="${NEXION_CLI:-nexion}"
pane=$("$NEXION" pane list --all --every-space --json | jq -r '
  (map(select(.agentState == "waiting")) + map(select(.finishedUnseen == true)))
  | first | .id // empty')
if [ -z "$pane" ]; then echo "No agent is waiting."; exit 0; fi
"$NEXION" pane focus --pane-id "$pane"

State log

Appends every state change to a JSONL file. report prints the total time spent in each state.

agent-log.sh
#!/bin/bash
# Appends every agent state change to a JSONL file.
#   ./agent-log.sh            # record (keeps running)
#   ./agent-log.sh report     # total time per state
NEXION="${NEXION_CLI:-nexion}"
LOG="${AGENT_LOG:-$HOME/.nexion/agent-states.jsonl}"
if [ "$1" = report ]; then
  jq -s -r '
    def t: sub("\\.[0-9]+Z$"; "Z") | fromdateiso8601;
    group_by(.paneId) | map(sort_by(.at) | [range(1; length) as $i | {state: .[$i-1].state, secs: ((.[$i].at|t) - (.[$i-1].at|t))}]) | flatten
    | group_by(.state) | map("\(.[0].state): \((map(.secs) | add / 60 * 10 | floor) / 10) min") | .[]' "$LOG"
  exit
fi
while true; do
  "$NEXION" event subscribe 'agent.*' | jq -c --unbuffered '.params | {at, paneId, agent, state, reason}' >> "$LOG"
  sleep 5
done

Other events and commands: CLI reference.