Run a command on an event

A hook runs a command of yours each time something happens in Blixel, such as
a call's transcript ending. Use one to save a summary of every call, or to
note when someone joins.

A hook runs after the event. It can't stop or change it. Blixel runs hooks
only while it is open; if it quits before a hook has run, the hook runs when
Blixel opens again.

Add a hook

1. Open Blixel's Settings and choose Hooks.
2. Click Add Hook….
3. Fill in the editor:
   • ID: a name for the hook, in lowercase letters, digits and dashes,
     such as standup. It can't change once saved.
   • Events: one or more events, each with what it means. See
     Events.
   • Rooms: Any room, or the rooms the hook runs for.
   • Command: what to run, such as ~/bin/summarize.sh.
   • Timeout (seconds): how long a run may take. The default is 300.
   • Retries: how many more times to try a run that fails. The default
     is 2.
4. Click Save. Nothing is saved until you do. Cancel leaves your hooks
   as they were.

A new hook runs only for events that happen after you add it.

Manage your hooks

The Hooks page lists each hook with its events, its rooms and its last run. A
warning sign shows that the last run failed.

• Enabled turns a hook on or off at once. Turning it off stops a run in
  progress. Turned on again, it runs the events it missed while it was off.
• Click a hook to edit it. Changing its events or rooms doesn't run again what
  it already ran.
• Recent runs shows its five newest runs. Open Log shows what a run
  printed. Run Again runs a failed one once more.
• Test with Latest Matching Event runs the command once now, for the newest
  event that matches the hook, even one it already ran. Save and enable the
  hook first.
• Remove… asks first, then deletes the hook with its runs and logs.

When a hook gives up on an event after its retries, macOS shows a
notification. To stop these, turn off Notify me when a hook gives up.

Example: save a summary when a call ends

This script exports a call's transcript and has Claude Code summarize it into
~/Standups:

#!/bin/sh
set -e
mkdir -p ~/Standups
transcript=$(blixel transcript export "$BLIXEL_TRANSCRIPT_ID" --format md)
printf '%s\n' "$transcript" | claude -p "Summarize this meeting." > ~/Standups/"$BLIXEL_TRANSCRIPT_ID".md

1. Save it as ~/bin/summarize.sh, and run chmod +x ~/bin/summarize.sh.
2. Add a hook with the event transcript.ended, your standup room, and the
   command ~/bin/summarize.sh.

The script gets the transcript's id as BLIXEL_TRANSCRIPT_ID. With set -e, a
failed export fails the run, so Blixel tries it again. The command runs in your
login shell, so blixel and claude must be on the PATH it sets: see
Use blixel in your terminal
and What a command receives.

From the command line

blixel hook add standup --type transcript.ended --room <room-id> --command ~/bin/summarize.sh
blixel hook list
blixel hook disable standup
blixel hook remove standup

blixel hook adds, edits, enables, disables and removes hooks, with Blixel
open or closed. blixel room list gives each room's id. For every option, run
blixel help hook add.

The hooks.json file

Hooks are saved in ~/.blixel/hooks.json. The Hooks page and blixel hook
both write it, and you can edit it by hand:

{"hooks":[{"id":"standup","enabled":true,"types":["transcript.ended"],
  "room_ids":["9f…"],"command":"~/bin/summarize.sh",
  "timeout_seconds":300,"retries":2}]}

• Blixel reads the file again before each event, so an edit counts from the
  next one, with no restart.
• While the file has an error, such as a missing required key or two hooks
  with one id, no hook runs. The Hooks page says why and saves nothing until
  you fix it.
• A hook Blixel can't run as written, such as one with an event type it
  doesn't know, is turned off and the Hooks page says why. The others keep
  running.
• Blixel keeps keys it doesn't know when it saves.
• Removing a hook from the file deletes its runs and logs. If the whole file is
  missing, no hook runs, and each one picks up where it was when the file comes
  back.