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 |
state | working, idle, waiting (waiting for user input) or exited. The same values nexion pane list reports as agentState. |
previous | Previous state. null in the initial events and when an agent starts. |
reason | finished, question, permission, error, exited or null. Provided by Claude Code hooks; usually null for other agents. |
agent | claude, codex, opencode, gemini, or another recognised agent. |
paneId, tabId, windowId, spaceId | Ids of the pane and its location. paneId is the id printed by pane list and accepted by pane focus --pane-id. |
cwd, projectName | Working directory of the pane, and the tab name shown in the sidebar. |
title | Terminal title set by the program (Claude Code writes a short topic). |
focused | true when the pane is focused in the key window and Nexion is the active app. |
at | Timestamp, 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.