Claude.Hooks.Reporter behaviour (claude v0.5.2)

A behaviour for implementing hook event reporters and dispatching events to them.

Reporters receive raw Claude Code hook events and handle them according to their implementation (webhooks, files, metrics, etc).

Implementing a Reporter

To create a custom reporter, implement the report/2 callback:

defmodule MyApp.CustomReporter do
  @behaviour Claude.Hooks.Reporter

  @impl true
  def report(event_data, opts) do
    :ok
  end
end

Configuration

Reporters are configured in .claude.exs:

%{
  reporters: [
    {:webhook, url: "https://example.com/events"},
    {MyApp.CustomReporter, custom_option: "value"}
  ]
}

Dispatching Events

The dispatcher is called automatically by the hooks system:

Claude.Hooks.Reporter.dispatch(event_data, config)

Summary

Types

event_data()

opts()

report_result()

Callbacks

report(event_data, opts)

Called for each hook event that needs to be reported.

Functions

dispatch(event_data, config, opts \\ [])

Dispatches an event to all configured and enabled reporters.

Types

event_data()

@type event_data() :: map()

opts()

@type opts() :: keyword()

report_result()

@type report_result() :: :ok | {:error, term()}

Callbacks

report(event_data, opts)

@callback report(event_data(), opts()) :: report_result()

Called for each hook event that needs to be reported.

The event_data is the raw JSON data from Claude Code's hook system, containing fields like:

"hook_event_name" - The type of event
"tool_name" - For tool-related events
"session_id" - Unique session identifier
Event-specific fields

The opts come directly from the reporter configuration in .claude.exs.

This function should handle its own error recovery and logging. Return :ok for success or {:error, reason} for failure.

Example

@impl true
def report(event_data, opts) do
  case send_to_service(event_data, opts) do
    {:ok, _} -> :ok
    {:error, reason} -> {:error, reason}
  end
end

Functions

dispatch(event_data, config, opts \\ [])

@spec dispatch(event_data(), config :: map(), keyword()) :: :ok

Dispatches an event to all configured and enabled reporters.

Reads the :reporters configuration from the provided config map, filters for enabled reporters, and executes each one asynchronously.

Errors from individual reporters are logged but don't affect other reporters.

Options

:async (boolean) - Whether to run reporters asynchronously. Defaults to true.

Example

Claude.Hooks.Reporter.dispatch(event_data, config)