Sirio

Working with agents

Hooks and sirioctl notify

How an agent tells Sirio it is running, waiting or done.

sirioctl notify is the command agents call to report their state. Sirio generates the hook configuration that invokes it when it launches an agent.

The call

sirioctl notify --session "$SIRIO_PANE_ID" --status running
sirioctl notify --session "$SIRIO_PANE_ID" --status needs-input
sirioctl notify --session "$SIRIO_PANE_ID" --status done

--status accepts running, needs-input, done and error. The same command with --title and a message posts a desktop notification instead.

Where the hooks come from

  • Claude Code: a worktree-local settings file with SessionStart, UserPromptSubmit, Stop, Notification and SessionEnd hooks.
  • Codex: a -c notify=[…] command-line override; Sirio writes the JSON inside it without escaped slashes because Codex parses the override as TOML.
  • Oh-My-Pi: a generated hook script the CLI is pointed at.

Sirio installs nothing for OpenCode or Pi and detects them from their titles and processes.

Turning it off

Disabling the control socket in Settings → General disables hooks as well: launched agents fall back to title and process detection.