A tiny project found the missing output channel.
Clanking maps coding-agent hook events to synthesized cues. Tool calls become short ticks. Separate cues mark output, permission requests, completion, and failure. A daemon receives later events, quantizes them to a beat, and sends raw audio to PipeWire through pw-cat.[1]
The repository also assigns a stereo position from each session's working directory. Its source hashes the directory, maps the result across a limited left-right width, and uses constant-power gains. Two concurrent jobs can occupy different parts of the stereo field instead of piling into one alert tone.[2]
This is useful because it asks less of your eyes, not because it makes the agent trustworthy.
Peripheral hearing has an old systems pedigree.
Michael Gilfix and Alva Couch described Peep at LISA 2000. Their network monitor mixed event, state, and heartbeat sounds into a background environment. The operator could notice a change without stopping work to inspect another screen. The paper also treated silence as information. A missing heartbeat could reveal that a monitored service or the monitor itself had stopped.[3]
Clanking applies that idea to coding agents. The useful unit is not a spoken log line. It is a short, distinct cue that answers one question. Is the agent active? Does it need me? Did it finish? Did it fail?
Do not turn the office into a slot machine.
Sound should start only after a deliberate action. MDN's Web Audio guidance says to create or resume an audio context inside a user gesture. It also recommends play, stop, volume, and mute controls with clear labels.[4]
Keep frequent cues below rare cues. Clanking's current source sets tool ticks quieter than most event cues. It also bounds the PipeWire buffer so queued audio stays short. Those choices protect the relationship between a current event and the sound that represents it.[2]
Keep proof on screen.
An audio cue can report that a hook fired. It cannot prove that a test passed, a patch matches the request, or a deployment reached production. Pair each cue with a visible event name, timestamp, run identity, and inspectable output. Treat sound as navigation to evidence.
The practical rule is simple. Use audio for state changes that deserve attention. Use text and artifacts for claims that deserve review.