Attend and Monitor¶
This directory documents the active awareness layer. Attend gives a session the awareness an employee would otherwise have ambiently — what is changing, who else is working, what deserves attention. Mechanically, it rides on top of Claude Code's Monitor tool to surface environmental changes as async notifications into a running session, and humans and other Claude agents can both participate in the same signal stream.
The thesis¶
Monitor is Claude Code's general-purpose async delivery mechanism: launch a command, stream its stdout as notifications. Anthropic's assumption in designing it seems to be that Claude will wire up whatever ad-hoc command fits the moment — a tail -f, a cargo watch, a bespoke shell pipeline — and let Monitor relay whatever comes out. That's a powerful primitive but it puts the burden on every Claude session to reinvent the observation logic from scratch.
Attend is Monitor with intention. It's a long-lived logic module that Claude doesn't have to tune case by case. It knows what kinds of changes matter, it governs the rate of environmental events through a formal engagement model (ADR-123, borrowing the activation-decay shape from ACT-R), it routes messages between peer agents through channels (ADR-118, ADR-173) on a message lane that never drops them, and it cleans up after itself by reaping the messages of projects that are gone (both ADR-136). Its event-lane governor is alarm management (ISA-18.2) applied to agent notifications — rate-limiting what reaches the conversation so the channel stays trustworthy instead of noisy. A Claude session drops into attend and gets a stable, opinionated awareness channel for free.
Said another way: Monitor is a delivery mechanism; attend is the editorial layer that decides what's worth delivering. That editorial policy is calm technology (Weiser & Brown) applied to a coding session: most changes stay in the periphery, and only what deserves attention moves to the center. The combination turns "sporadic unpredictable state" into a structured stream of observations the agent can act on.
The pair¶
Attend is a sensor loop. It watches the local environment (git state, peer sessions, context pressure, process activity, peer messages, and any sensor a user adds as a file) and emits observations when something crosses a threshold. It runs as a single long-lived process inside the Claude Code session.
Monitor is the Claude Code tool feature that launches a command and delivers each line of its stdout as an asynchronous notification into the conversation. It's general-purpose: build watchers, test runners, deploy pipelines, custom event logs all fit.
The common thread across every Monitor use case is sporadic unpredictable state — changes the agent didn't cause, arriving at unknown times, that still need to land in the conversation in time to affect the next decision. Attend is one class of sporadic state — the class that comes from complex interactions across peer agents plus ambient environmental awareness. A build watcher is another class. They share the mechanism; they differ in what they observe.
Two consumers, one channel¶
Attend is not exclusively for AI agents. A human can launch it too, and both consumers share the same signal bus. The peer layer underneath is workspace awareness (Dourish & Bellotti's CSCW term) applied to coding agents — knowing who else is working, where, and what they said — served to humans and agents through one protocol.
Agent mode — attend run: An AI agent session invokes attend through Monitor. The sensor loop emits notifications into the conversation, and a Stop hook delivers pending messages at the end of each turn. The agent responds to what it sees, sends peer messages back through attend message send, and participates in channels through attend channel join. See loop.md for the sensor loop and delivery.md for the two delivery conduits. In Claude Code the attend mod takes Monitor's place: a session listens when its project is set active or when the user asks for attend, and the mod delivers, draws a status row and serves typed tools (mod.md).
Human mode — attend chat: A human opens attend-chat, a terminal chat screen on the same message bus. Every channel streams into it, and the human addresses Claude agents (@Elio ship it, @Elio @Lachlan sync first, #deploy hold) through the same signal files the agents use, and steers a multi-agent session from one surface. See tui.md.
The phrase that captures it: humans wear the same clothes as an AI agent as far as attend is concerned. Same signal protocol, same routing, same channels. The human just happens to have a keyboard and eyeballs instead of a context window.
This dual-consumer property is deliberate. It means the signal protocol is dogfooded — the human feels the routing semantics directly, and any friction in how messages land is friction the agents also experience. It also means a solo developer watching one agent gets as much value as a coordinator orchestrating four.
Scale context¶
The attend development effort so far has put significant weight on the multi-agent peer-messaging story: channels, the message lane, turn-boundary delivery, cross-session signal routing. That's a real use case but it's not the common one. Most uses of attend will be single-user: one human, one Claude agent, external state sources.
The common-case shape looks like this: you're writing code, Claude is helping, and you want the session to notice things that happen outside the conversation — a make test finished, an issue got assigned to you on GitHub, a long-running deploy finished. Attend's sensors feed those into the conversation without you having to interrupt and ask "what's the status?" The peer-messaging layer is still there if you ever run four agents at once, but you don't have to opt into it to get value.
This is why sensors of your own are a first-class design surface — they're the bridge between attend's formal engagement model and whatever the user actually cares about watching. See the next section.
Sensor authorship is a design surface¶
Every sensor is one YAML file under one spec (ADR-403), layered by name: the files attend ships, then your own under $XDG_CONFIG_HOME/attend/sensors/, then a project's under .claude/attend/sensors/. A file's kind says what polls:
crateconfigures a compiled sensor: a Rust crate or attend module implementing theSensortrait fromsensor-trait. The shipped sensors are of this kind:context,gitanddisclosure(modules of attend itself, always compiled), and thesensor-peers,sensor-processesandsensor-keepwarmcrates. A file of your own changes any of their fields without a rebuild.commandruns an argv and reads its output, andmcpcalls one read-only tool on a stdio MCP server. Neither needs Rust or a recompile. attend loads, checks and lists both now, and runs them from ADR-403 slices 2 and 3. The shippedexample-command.yamlandexample-mcp.yamlare the patterns to copy.
Every kind shares one constraint: the sensor author has to understand the loop's intention. Events are not log lines — they're magnitude-weighted observations that feed an accumulator, decay over time, and fire disclosure only when they cross a refractory-aware threshold. A sensor that emits "something happened" on every tick will either flood the governor or get suppressed into silence by action potential. A well-designed sensor encodes how much each kind of change matters in the event magnitude, and lets the loop handle the rest.
See authoring-sensors.md for the spec and the author's guide.
What lives in this directory¶
| File | Purpose |
|---|---|
README.md |
Orientation — you are here |
loop.md |
The sensor loop — state diagrams, timing, the two lanes |
first-sensor.md |
Walkthrough — write your first sensor file |
authoring-sensors.md |
The sensor file spec and writing sensors (reference) |
sensors.md |
The shipped sensors, their states, and what each observes and emits |
engagement.md |
The action-potential model on the event lane |
signals.md |
Signal file format, storage layout, lifecycle |
delivery.md |
The Monitor line and the Stop-hook drain, enrollment, opt-out |
mod.md |
The attend mod in Claude Code: dormant and active sessions, its config, install |
channels.md |
Channel membership and lifecycle |
tui.md |
attend chat — the human on the bus |
keepwarm.md |
Holding the prompt cache warm across idle time |
configuration.md |
Config schema, overlay semantics, permissions |
../cli/attend.md |
The attend CLI reference, generated from the binary |
Reading order¶
loop.md— if you only read one file, read this. The sensor loop is the substrate everything else rides on.delivery.md— how a peer message reaches a session, and how to opt out.tui.md— if you're a human using attend directly, or coordinating multiple agents.first-sensor.md— if you want to tune or write a sensor and you've never done it before.authoring-sensors.md— the sensor file spec and design surface once the tutorial isn't enough.sensors.md,engagement.md,signals.md,channels.md,keepwarm.md,configuration.md— reference, read as needed.
The scenarios in ../explanation/attend-messaging/ show the message lane at work with one, two and many Claudes and a human.
Related docs¶
../vocabulary.md— terminology anchors mapping the project's coined terms to their established concepts (ADR-301)- ADR-113 (
docs/architecture/ways/) — the original decision to build attend as an active awareness module - ADR-114 — attend as an insistent trigger type for ways
- ADR-115 — declarative config with project-scope overlay
- ADR-116 — permission requirements
- ADR-117 — sensor crate extraction
- ADR-118 — channels (introduced as focus groups), dynamic agent grouping
- ADR-119 — action potential engagement model (superseded by ADR-123)
- ADR-120 — interactive chat TUI, human in the signal loop
- ADR-122 — the disclosure sensor
- ADR-123 — firing dynamics unification; the engagement engine in force
- ADR-136 — the message lane, split from the event lane
- ADR-172 — turn-boundary delivery through the Stop-hook drain
- ADR-173 — the chat idiom: channels,
join/leave, tabs and slash commands - ADR-182 — keepwarm
- ADR-403 — sensors as files under one spec: crate, command and mcp
docs/hooks-and-ways/— sibling docs for the synchronous hook mechanismdocs/architecture/practice/ADR-600-cognitive-loop-and-the-awareness-layer.md— earlier design exploration that informed ADR-113
Where the code lives¶
tools/attend/— orchestrator and CLI;../cli/attend.mdlists every subcommandtools/attend-chat/— the chat screen, onagent-tuitools/attend-groups/,attend-presence/,attend-state/,attend-config/— channels, heartbeats and enrollment, the per-session seen-set, the config schematools/sensor-trait/— baseSensortrait,SensorSlot, engagement statetools/attend/src/sensors/(context,git,disclosure),tools/sensor-peers/,sensor-processes/,sensor-keepwarm/— the compiled sensorsattend/sensors/— the shipped sensor files;tools/sensor-spec/parses, layers and checks them, andtools/attend-config/src/sensors.rsfinds themhooks/ways/attend-drain-stop.sh— the Stop hook that drains messages at the turn boundarytools/agent-fmt/— shared terminal formatting (banners, tables, commands)skills/attend/SKILL.md— the invocation skill the agent reads when the user asks for awarenesshooks/ways/softwaredev/environment/attend/— the way that surfaces live attend state in the steering layer