Your first sensor file¶
This walkthrough writes sensor files by hand, sees attend pick them up, and sends test results through them. It tunes a shipped sensor for yourself, switches one off for a project, reads what a mistake looks like, and starts a command sensor from the shipped example. authoring-sensors.md is the spec behind each step.
You need an attend that reads sensor files (ADR-403): attend sensor list prints Kind and Origin columns. You do not need Rust. The paths below use ~/.config for $XDG_CONFIG_HOME.
Step 1 — See what runs¶
$ attend sensor list
Sensor Kind Origin State Lane Interval Source File
─────────────────────────────────────────────────────────────────────────────────────
context crate builtin active event 60s / 20s attend@0.33.0 -
...
processes crate builtin active event 30s / 5s sensor-processes@0.6.0 -
Each row is one sensor and its files merged. Every row here is builtin: the files attend ships, under attend/sensors/ in the repository. processes reports build tools that finish, at a threshold of 2.0.
Step 2 — Tune a shipped sensor for yourself¶
Make the user directory and write a file named after the sensor:
mkdir -p ~/.config/attend/sensors
cat > ~/.config/attend/sensors/processes.yaml <<'EOF'
threshold: 3.0
watch: [cargo, rustc, make]
EOF
The file carries only what it changes. It merges over the shipped processes.yaml, so kind, crate and the intervals come from there. watch is a field of the compiled processes sensor: these three tools get build enrichment, and the default list is replaced.
$ attend sensor list
...
processes crate builtin · user extends active event 30s / 5s sensor-processes@0.6.0 ~/.config/attend/sensors/processes.yaml
Origin is now builtin · user extends and File names your file. A running attend run sees the change and reloads.
Step 3 — Send a test through it¶
attend sensor fire passes a synthetic result through the sensor's real threshold and lane. --dry-run stops before delivery.
$ echo "2.5|cargo finished" | attend sensor fire processes --input - --dry-run
processes: held on the event lane: 2.5 accumulated of a 3.0 threshold
One observation at 2.5 is under the new threshold, so it waits in the accumulator. Two smaller ones add up:
$ printf '1.5|cargo finished\n1.5|make finished\n' | attend sensor fire processes --input -
[attend sensor=processes priority=medium] [test] cargo finished
[attend sensor=processes priority=medium] [test] make finished
processes: delivered on the event lane at priority medium
Without --dry-run the lines print as attend run prints them, each marked [test]. Magnitude is the lever: at 3.0 or more a batch is medium priority and wakes the agent, below it attend logs it and wakes no one. A fire records nothing in the sensor's store.
Step 4 — Switch a sensor off for one project¶
In a project you work in, write a project file:
Run from that project, attend sensor list shows git with Origin project and State off, and attend run there does not poll it. A project file that changes a crate sensor needs no permission. A project's command or mcp file runs code the repository chose, so it loads only once you list the project in project_sensors in ~/.config/attend/config.yaml.
Step 5 — Read a mistake¶
Change the threshold in your user file to a word:
attend sensor list now shows processes as invalid, and the line under the table says why:
An invalid sensor does not run, and the shipped file does not stand in for it. ways settings lint names the file and the line, beside the findings of every other settings file. Set the threshold back to 3.0 and the sensor is active again.
Step 6 — Start a command sensor from the example¶
example-command.yaml is a complete command sensor, shipped off, with every field commented. It reports systemd user units that fail. Copy it under a name of your own, from the app dir or from attend/sensors/ in a checkout:
cp "${XDG_DATA_HOME:-$HOME/.local/share}/agent-ways/attend/sensors/example-command.yaml" \
~/.config/attend/sensors/failed-units.yaml
A sensor's name is its file's stem, so set name: failed-units in the copy, and enabled: true. Read the comments while you are there: argv and output say what runs and how its output reads, state says what attend keeps between polls, and each trigger says which change wakes the agent.
$ attend sensor list
...
failed-units command user degraded event 300s / 60s sh ~/.config/attend/sensors/failed-units.yaml
...
failed-units: degraded: kind command not yet hosted; attend runs command sensors from ADR-403 slice 2
attend loads, checks and lists command sensors now, and runs them from ADR-403 slice 2. ways settings lint checks the file today: change a trigger's on: added to on: appeared and lint names the line.
Clean up¶
rm ~/.config/attend/sensors/processes.yaml ~/.config/attend/sensors/failed-units.yaml
rm .claude/attend/sensors/git.yaml
With the files gone, each sensor reads from its shipped file again.
Where to go next¶
authoring-sensors.md— every field of every kind, triggers, state, lanes and the project allow-list.sensors.md— what each shipped sensor observes and the magnitudes it emits.example-mcp.yamlbeside the command example — the pattern for a sensor that reads an MCP tool.