Start a listener
Have your agent listen to the documents you're working on, so a comment or a mention reaches it and it replies in the thread.
Have your agent do it
Paste this to your agent. It reads this guide and works through it with you.
Read https://avalandra.com/help/start-a-listener.md and do it with me. Ask me before you decide anything the guide leaves to me, and tell me what you did when you're done.A listener is your agent keeping watch on a few documents. When someone comments on one of them, replies in a thread or mentions your agent, the listener passes it to your agent. Your agent does what was asked and answers in the same thread, so the work and the conversation stay together on the document.
For example, your agent listens to a brief you're writing. A teammate comments to ask what was decided about a detail, and your agent replies with the decision and a link to where it was made.
Before you start
- Your agent is connected with the install command, such as Claude Code, Codex or Cursor. See Connect your agent. Claude through the connector can't listen; it sees new comments when it checks in.
- You know which documents it should listen to. One listener covers documents in one Space.
Start it
- Pick the documents. Choose the documents you're working on now, such as a brief and its checklist.
- Ask your agent to listen. Say what it should do when a comment arrives, and when to finish a thread.
- Look for it in Avalandra. Your agent shows as listening on those documents.
- Try it. Select some text in one of the documents, write a request, and press ⌘ Enter. Your agent should reply in the thread.
Start listening to [the documents you're working on] in the [name of your Space] Space. When someone comments or mentions you, do what they ask, reply in the thread with what you did and a link to any source, and resolve the thread when it's done. If you're not sure what they want, ask in the thread. Keep listening until I tell you to stop.Give your agent a task from a comment
On a document your agent is listening to, how you send a comment decides who it's for:
- ⌘ Enter (Ctrl Enter on Windows) sends the comment to your listening agent as a task. The hint under the comment box reads "⌘↵ asks agent" when an agent can take it.
- Enter leaves a normal comment for the people who can see the document.
- @mentions reach someone specific. Mention a person, or a particular person's agent, such as "@[Teammate]'s agent (Codex)".
Text (Markdown) documents work a little differently. There, Enter adds a new line and ⌘ Enter posts the comment.
Listen to every document your agent creates
A document your agent has just written is where questions about it will land. Instead of asking it to listen each time, give your agent a standing instruction to start listening to every document it creates in Avalandra, straight away. In Claude Code that's a skill; in other tools it's the standing instructions file, such as AGENTS.md.
Set up a skill (or a standing instruction, if your tool doesn't have skills) called "listen to new Avalandra documents". Whenever you create a document in Avalandra, start listening to it right away, alongside any documents you're already listening to in that Space, and tell me you're listening. When someone comments or mentions you on it, follow https://avalandra.com/help/start-a-listener.md. Show me the skill before you save it.Your agent only listens while it's running, so the skill takes effect in sessions where your agent is open.
Keep it running
Your agent listens while it's running, so keep its session open, or ask it to start listening again when you come back. Avalandra keeps the listener for 14 days without a connection. Comments left while your agent was away are still waiting for it when it starts listening again.
Questions
What's the difference between a listener and asking my agent directly?
When you ask your agent, you start the work. With a listener, anyone on the team can start it by commenting on the document, and the answer stays in the thread for everyone to read.
Does my agent keep listening when I close it?
It listens while it's running. When you start it again, ask it to listen again. Comments that arrived in the meantime are still waiting for it.
Can my agent start listening on its own when it writes a document?
Yes. Give it a skill or standing instruction to listen to every document it creates. See Listen to every document your agent creates.
How many documents can one listener follow?
Documents in one Space. Avalandra groups them 20 at a time and splits longer lists for you, so you can name more than 20.
Can a teammate's comment start my agent working?
Yes, if your agent is listening to that document and the teammate sends the comment to it with ⌘ Enter or mentions it. It works with your permissions, so it can only do what you can do in that Space.
For agents
ava listen --space SPACE_ID --document DOC_ID --document DOC_ID --name NAME --follow --jsonl
ava comment ack THREAD_ID
ava comment resolve THREAD_ID
ava comment release THREAD_ID
ava listenprints one JSON line per item. Without--followit exits after the first batch, or after--timeout(default 30m) with no output; loop it to keep listening. With--followit streams until interrupted.- With
--spaceand--documentthe person sees you listening in the web app. Name the listener with--name;--idle-ttlsets how long it survives without a connection (default 14d). --kindslimits what you receive:thread,reply,mention,review_request,review_update,edit.- A comment sent with ⌘ Enter on an HTML document is routed to the listening agent as a task. A plain Enter comment is for people; act on it only if it mentions you.
- For each item, read the thread, do the work and reply in the thread (
ava document comment replyorava document text-comment reply), thenackto keep it open,resolvewhen it's done, orreleaseto hand it back. - Ask in the thread when the request is unclear. Don't guess, and don't act outside what the person asked the listener to do.
- For a "listen to new documents" skill: after every successful
ava document create, add the new document id to your listener for that Space by runningava listenagain with the same--name,--spaceand all the--documentids you're following, plus the new one. Tell the person which documents you're now listening to. ava agent check-in --jsonlists everything directed at you across Spaces, read-only, if you need to catch up after a gap.