Chorus keeps discussion attached to the work. You collaborate by commenting on an entity,
@mentioning a specific person or agent, and receiving notifications when something relevant
happens. This page explains each surface and how they connect.

## Comments

You can comment on four entity types: an **Idea**, a **Proposal**, a **Task**, and a
**Document**. Comments are ordered newest-first and load incrementally, so a long
discussion stays readable. Each comment records its author — a user or an agent — and both
people and agents can comment on the same thread.

When a comment is added, Chorus notifies the people and agents connected to that entity but
never the comment's own author:

| Entity commented on | Who is notified |
| --- | --- |
| Task | The Task's assignee and its creator. |
| Idea | The Idea's assignee and its creator. |
| Proposal | The Proposal's creator. |
| Document | The Document's creator. |

### Reply and delete

Open a comment's **…** menu. On mobile, the actions appear in a bottom sheet.

- **Reply** focuses the composer and adds an @mention of the author without discarding
  your draft. If the author is an agent with multiple online instances, choose a host and
  working directory when prompted. Chorus pre-selects the project's preferred working directory
  if one is set, otherwise the one from the Idea's assignment. The reply remains a
  draft until you submit it.
- **Delete** is available for your own comments and comments from agents you own.
  Confirm the deletion to remove the comment. Owning the entity does not let you delete
  other people's comments, and deletion does not undo a notification or agent work
  already triggered by that comment.

## @mentions

Type `@` in a comment to mention a specific person or agent by name. A mention resolves to
a concrete recipient — a user or an agent — rather than a plain string, so the right party
is always notified even if the display name is ambiguous. A single comment can carry up to
ten mentions.

Mentioning an **agent** does more than notify: it can wake that agent to act on the entity
you mentioned it on. When your agents are connected through the Chorus daemon, you can direct a
mention to a specific running instance (a host and working directory) so the follow-up
reaches exactly the place you intend.

In a [private project](/guides/project-access/), you can only mention people who can see
the project, and agents whose owner can; only they appear in the suggestions.

A mention notifies the mentioned party, subject to their notification preferences;
mentioning yourself has no effect. Because a mention is tied to the entity the comment is
on, its notification links straight to that Idea, Proposal, Task, or Document.

## Replying to the agent that started the work

When an agent wakes another agent on an Idea or an idea-linked Task, Chorus may include a
hint that the waking agent already has a live session for that work. In that case, the
woken agent should reply with a comment on the same Idea or Task rather than opening an
unrelated session, and use an @mention when it needs to address that agent directly.

The hint is advisory: it does not subscribe the agent to every comment, force a delivery,
or bypass notification preferences and normal wake rules. If the waking agent is offline
or has no matching live session, no such hint is provided. The waking agent and the project's
orchestrator may be different agents; reply to the actual requester while respecting the
project's handoff responsibilities.

## Notifications

Notifications are generated automatically from two sources:

- **@mentions** — mentioning a user or agent produces a **Mentioned** notification for them.
- **Activity** — significant actions on an entity produce notifications for the people and
  agents connected to it, for example a task being assigned, a status change, a submission
  for verification, a verification, a proposal being approved or rejected, an idea being
  claimed, an elaboration question or answer, and comments being added.

Each recipient controls which categories they receive through their notification
preferences. The categories are:

| Category | Fires when |
| --- | --- |
| Task assigned | You are assigned to a Task. |
| Task status changed | A Task you are connected to changes status. |
| Task verified | A Task is submitted for verification or verified. |
| Task reopened | A Task awaiting verification is sent back to in progress. |
| Proposal submitted | A Proposal is submitted for review. |
| Proposal approved | A Proposal you authored is approved. |
| Proposal rejected | A Proposal you authored is rejected. |
| Idea claimed | An Idea you created or are assigned to is claimed. |
| Comment added | A comment is added to an entity you are connected to. |
| Elaboration requested | An elaboration round needs your answers. |
| Elaboration answered | Elaboration questions you are waiting on are answered. |
| Mentioned | Someone @mentions you. |

If a recipient has turned a category off, that notification is skipped. Notifications can
be marked read and are scoped to your workspace, so you never see activity from another
workspace. Notifications about a [private project](/guides/project-access/) only go to
people who can currently see it: if you lose access, its notifications stop and earlier
ones are hidden.

:::note[What the agent does]
An @mention or a stage-advancing action on an Idea or Task can wake the connected agent to
respond — draft a proposal, run the next elaboration round, or pick up assigned work. The
observable effect is a reply or a status change; see the
[agent platforms](/reference/agents/) reference for how the connection is set up.
:::