hooks

Run arbitrary shell commands at well-defined points in the Blaze CLI lifecycle. Use this to log history, send desktop notifications, or run your own automation scripts when Blaze starts, stops, compacts a conversation, or finishes a response.

When hooks fire

Four events are supported today:

• SessionStart — right after a Blaze session begins (before the first input is read)
• SessionEnd — right after the session ends (before the terminal closes)
• PreCompact — just before /compact compresses the conversation
• Stop — right after Blaze finishes responding (both success and error)

Configuration file

Hooks live in ~/.blaze/settings.json (per environment: production = .blaze, staging = .blaze-stg, development = .blaze-dev). Create the file if it does not exist.

Basic shape:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          { "type": "command", "command": "echo started >> ~/blaze.log" }
        ]
      }
    ]
  }
}

hooks.<Event> is an array — you can register multiple groups, each with multiple commands.

What gets passed to your command

Each command receives the following JSON on stdin:

{
  "session_id": "01HXXXXXXXXXXXXXXXXX",
  "transcript_path": "",
  "cwd": "/Users/you/projects/my-org",
  "hook_event_name": "SessionStart"
}

Use jq, Python, or any tool to pick out the fields you need.

Example: log every session

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '\"[\\(.hook_event_name)] \\(.session_id) cwd=\\(.cwd)\"' >> ~/blaze.log"
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '\"[\\(.hook_event_name)] \\(.session_id)\"' >> ~/blaze.log"
          }
        ]
      }
    ]
  }
}

Example: desktop notification on response complete (macOS)

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Blaze finished\" with title \"Blaze CLI\"'"
          }
        ]
      }
    ]
  }
}

Behavior notes

• Each command runs through a shell (sh -c on Unix, cmd /C on Windows)

• Timeout is 10 seconds — commands that exceed this are killed

• A non-zero exit does not break Blaze — only a warn is logged

• Fire-and-forget: Blaze does not wait for hooks to complete

• Missing settings file, broken JSON, or an absent event array all mean “no hooks” — Blaze starts and runs normally

Troubleshooting

If your hook is not running, check in this order:

1. ~/.blaze/settings.json is valid JSON (cat ~/.blaze/settings.json | jq . parses it)

2. The event name in hooks.<Event> exactly matches one of Stop / SessionStart / SessionEnd / PreCompact (case-sensitive)

3. Each entry’s type is "command"

4. The command runs standalone in your terminal (PATH and permission issues affect hooks the same way)