Creating Custom Sensors

Sensors are shell scripts that run as Claude Code hooks. You can create custom sensors alongside catalog-provided ones.

How It Works

Create a file in agent/Sensors/ (e.g., agent/Sensors/my-sensor.sh)
Add YAML frontmatter with description, event, and optionally matcher
Run bonsai update — it detects untracked files and offers to track them
Once tracked, custom sensors appear in CLAUDE.md, .bonsai.yaml, and .claude/settings.json

Frontmatter Format

Sensors need extra fields compared to skills:

---
description: Blocks risky operations on Fridays
display_name: Friday Guard
event: PreToolUse
matcher: Bash
---

#!/usr/bin/env bash
# Script content here
...

Field	Required	Notes
`description`	Yes	Shown in CLAUDE.md nav tables
`display_name`	No	Human-readable name
`event`	Yes	Hook event: `SessionStart`, `PreToolUse`, `PostToolUse`, `Stop`, `UserPromptSubmit`, `SubagentStop`
`matcher`	No	Tool filter (e.g., `Bash`, `Edit`, `Write`, `Edit\|Write`)

Available Events

Event	When it fires	Can block?
`SessionStart`	Beginning of a conversation	No
`UserPromptSubmit`	Before Claude processes a user message	Yes (exit code 2)
`PreToolUse`	Before a tool executes	Yes (exit code 2)
`PostToolUse`	After a tool executes	No
`Stop`	After every Claude response	Yes (exit code 2)
`SubagentStop`	When a dispatched subagent finishes	No

File Naming

Use kebab-case for filenames: my-custom-sensor.sh, not MyCustomSensor.sh
The filename (minus extension) becomes the item’s machine name
Use .sh extension

What `bonsai update` Does for Sensors

When you run bonsai update with custom sensors:

Detects untracked .sh files in agent/Sensors/
Validates frontmatter — warns if event is missing
Tracks in .bonsai.yaml and .bonsai-lock.yaml
Syncs .claude/settings.json hooks — adds hook entries for custom sensors
Refreshes CLAUDE.md nav tables