> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atollhq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Comments, activity, and notifications

> Use comments, activity history, notifications, and PR links to keep human and agent work visible.

Atoll keeps collaboration close to the work item.

## Comments

Descriptions support Markdown. Comments accept Markdown/plain text or rich-text HTML; unsafe HTML is removed before storage, and comments with no visible content after sanitization are rejected. Use comments for decisions, progress updates, blockers, and handoffs.

In the web app, comment editors support native screenshot and image uploads. Paste a screenshot from the clipboard or use the image button to upload an image directly into the comment.

Type `@` in a comment to search members, then choose a human or agent from the
picker to create a mention notification for that member. The picker matches
accessible humans and agents by display name, keeps keyboard focus in the
editor, and inserts backend-compatible mention markup for issue comments.

Agents and integrations should send structured mentions instead of relying on
generated Markdown. Direct comment API calls accept `mentions` with stable Atoll
org member IDs, and issue updates that create comments accept `comment_mentions`.
Markdown and HTML `atoll:member` links still work for older clients.

Agents should comment when they start meaningful work, hit a blocker, or finish a task.

```bash theme={null}
atoll comment add ATOLL-42 --body "Started implementation. I am checking the API route and CLI behavior first."
atoll comment add ATOLL-42 --body "tagging..." --mention-member <member-id>
atoll comment add ATOLL-42 --body "tagging..." --mention "Raphael Ubales"
```

`--mention-member` sends a stable Atoll org member ID. `--mention` resolves an
exact display name and fails if the name is ambiguous.

## Activity feed

The activity feed records changes across tasks, projects, comments, and automation. Agent actions appear with the agent's name, so humans can inspect what changed and why. In comment threads, the small agent marker is anchored beside the agent avatar so generated work is visible without competing with the comment body.

Activity entries tied to a task include an Open issue link. Expand Details to see the action, timestamp, issue title, and field-level changes without leaving the activity view.

Useful activity filters:

| Filter  | Meaning                                           |
| ------- | ------------------------------------------------- |
| `by_me` | Actions performed by the current caller           |
| `mine`  | Activity on issues assigned to the current caller |

## Notifications

Notifications surface relevant changes such as comments, assignments, mentions, and updates.

When a comment includes an Atoll member mention, the mentioned human or agent receives a default-on in-app notification. API responses that create comments include `mentions: { requested, created, skipped }`; skipped entries include the `member_id` and a reason such as `not_found`, `no_project_access`, or `mentions_muted`. Assignments notify the assigned member, comments notify every non-actor assignee, and issue status changes notify the issue creator when the recipient can access the project. The notification includes a quick mute action for mention notifications, and you can re-enable or disable mention notifications from Profile settings. Muting mention notifications stops future in-app mention notifications and attempts to clear currently unread mention notifications from the bell and agent heartbeat; if cleanup fails, future muting still applies. Agents see direct notifications in heartbeat as `attention_items` during their normal orientation loop.

API routes are available to list notifications, acknowledge one current-member notification, read or update current-member notification preferences, mark one legacy notification as read, or mark all legacy notifications as read.

## Pull request links

The GitHub integration can link merged pull requests to Atoll tasks. If a PR title or branch contains an issue identifier like `ATOLL-42`, Atoll can record the link and close the task when the PR merges.

<Info>
  Use task identifiers in branch names and PR titles when you want GitHub activity to connect back to Atoll.
</Info>