Docs

From install to first delivered event in five steps. Transforms are never edited in the browser — use the CLI or an MCP agent.

1. Install

Any package manager works. The CLI itself runs on bun — the curl installer sets that up for you.

bun add -g @thelacanians/hooksmith --registry https://packages.buildkite.com/the-lacanians/hooksmith/npm/

2. Connect your account

Log in with the same email and password as the dashboard — add --register the first time. The CLI stores a personal token in ~/.hooksmith; revoke a machine with logout.

terminal

hooksmith login --email you@domain --password '…'
hooksmith whoami

3. Create a transform

new opens the TUI: the agent drafts the YAML, you review the live preview and approve. test runs the transform against a sample payload locally.

terminal

hooksmith init
hooksmith new buildkite-agents
hooksmith test buildkite-agents --payload ./event.json

4. Deploy

Deploying returns your ingest URL. Point the webhook source at it and you're live.

terminal

hooksmith deploy buildkite-agents
# https://hooksmith.tech/h/<id>

5. Operate

Watch events from the terminal or the dashboard — both offer replay for any received event. Secrets (like destination URLs) are stored per workspace and referenced from YAML, never committed.

terminal

hooksmith logs                 # recent events
hooksmith events buildkite-agents
hooksmith replay <event-id>
hooksmith open buildkite-agents  # dashboard URL

6. Agent / MCP

The MCP server exposes the whole lifecycle as tools — including fix_with_agent for repairing a failing hook from a real event.

terminal

hooksmith mcp serve

7. Quiet hours

Add spec.quietHours so brrr stays quiet overnight. mode: defer queues the event and delivers the original payload when the window ends. mode: mute instead delivers now with interruption_level: passive and no sound.

hook.yaml

quietHours:
  timezone: America/Mexico_City
  window: "22:00-08:00"
  mode: defer
  applyTo:
    - brrr