Hooks

Hooks are structured automations that run when a supported coding tool emits a lifecycle event. Instead of adding more prompt text to every conversation, a hook waits for a specific event, optionally filters with a matcher, and then runs one or more handlers.

In the current braid runtime, hooks target Claude-compatible hook events.

When to use hooks

Use hooks when you want automation to happen at a specific moment:

• Run a shell command before or after tool use
• Call an internal HTTP endpoint when a task completes
• Trigger a prompt or agent-based check when the user submits a request
• Enforce lightweight guardrails around file, worktree, or session events

How hooks work

Each hook has:

• an event such as PreToolUse, PostToolUse, or SessionStart
• an optional matcher to narrow when it should run
• one or more handlers that define the actual action
• an enabled state so you can keep a hook installed without running it

Handler types

Some events allow every handler type. Others are more restricted. For example, file and session bootstrap events are command-only, while tool and task events support richer handler types.

Hooks vs rules vs skills

Authoring and installation

You can scaffold hook files in a manifest-backed pack repo with:

braid scaffold --type hook --name pre-tool-guard

Hook installs currently flow through pack and marketplace installs. On Claude-compatible targets, braid writes installed hooks into the local hook configuration and keeps metadata so they can be managed later.

Managing installed hooks

Use the local prompt manager to inspect, disable, enable, or remove installed hooks:

braid manage

There is not currently a dedicated braid hooks command group.

Next steps

• Learn how packs are structured in the marketplace docs
• See the full braid scaffold command reference
• Open braid manage to inspect installed bundles locally