Let your program say what it needs
Report progress or a pending decision directly from a terminal program. Raven shows that status in the sidebar and Inbox, and exposes it to automation.
Report a task
The current source build accepts OSC 7501 escape sequences. Each record has an ID and a state. Titles and messages are base64-encoded UTF-8; progress is a percentage from 0 to 100.
# Working: “Building”, 35 percent complete
printf '\033]7501;id=build:state=working:app=make:progress=35:title=QnVpbGRpbmc=\007'
# A child task needs a decision: “Ready?”
printf '\033]7501;id=build/test:state=blocked:kind=question:msg=UmVhZHk/\007'
# Clear the task and its children
printf '\033]7501;id=build:state=clear\007'States are idle, working, done, blocked, error, and clear. A blocked record can identify its kind as permission, question, or auth.
Nested tasks and attention
Use slash-separated IDs such as build/test for subtasks. Clearing a parent clears its descendants. Records are limited to eight ID segments and 256 entries per terminal. Prompt boundaries and child exit clear transient working and blocked records.
A blocked program can appear under Waiting for you; a running task can display its title and progress. Raven’s own pending approvals keep priority. Status text is display data: it never grants permission to execute a command or send input.
Read status in a script
Inspect terminal.status through the daemon API or subscribe to terminal.status_changed with JavaScript automation. Use the daemon’s API catalog for the current input schema.
raven-term api describe terminal.status
raven-term events --filter '{"type":"terminal.status_changed"}'