Listener & asks_wait

A listener wakes your agent when someone asks it a question on an artifact. You do not need one for solo work; start it when you share an artifact or want the agent to stay available.

Starting the listener

Ask your agent to listen for questions on your artifacts. It calls get_listener once per session with its harness: claude-code, codex, copilot, antigravity or generic. The result contains:

• the address of the listener script and its SHA-256 checksum, which the agent checks before running it;
• a setup command for that harness;
• a fallback to use if background processes are not possible.

The listener script needs Node.js 22 or later.

Without ids, the listener covers the 200 most recently updated artifacts you own or have joined with the commenter role or higher, and refreshes that list every 60 seconds, so new artifacts are picked up on their own.

The listener key

Each get_listener call creates a new listener-only key and puts it in the start command. That key can listen but cannot call any tool. Agents never print or share it. Only the five newest listener keys of a token stay active, and revoking the token revokes them too.

How agents wake up

• Claude Code runs the listener in the background with --once: it exits when questions arrive, the agent reads them with asks_list, answers, and starts the command again.
• Codex, Copilot CLI and Antigravity run it with --follow in a background terminal, which appends questions to ~/.blink/inbox.jsonl; at each turn the agent runs --drain to read the unread ones.
• generic uses --follow if the client can keep a background process running; otherwise you run it in your own terminal.

Database and document changes

A listener can also wake the agent for changes. Neither is on by default:

• db collections: pass db together with ids to get_listener. The agent wakes when rows in those collections change, then reads them with db_query.
• document changes: get_listener does not set these up. Add --changes <id,id> to the listener's start command yourself; with --ids, those artifacts must also be in --ids. The agent then wakes after people stop editing for a while, and calls changes_since and read_file.

asks_wait

Agents that cannot run or be woken by background processes can wait in a loop with asks_wait:

It returns at once if there is an open question newer than after, and otherwise waits and returns an empty list on timeout. Pass the returned cursor as after next time. While an agent waits in asks_wait, it shows as listening in the @ menu.