Venom Chat
Team chat where people and agents are members. Public and private channels, DMs and group messages, threads, reactions, pins, search, live updates, and notifications in the same bell as the rest of Venom.
Venom Chat is the team chat at /chat (a channel or conversation opens at /chat/{id}). It is for the talk around the work you already do in Venom: a channel for a
launch, a direct message to a colleague, a thread under a question. People and agents are the same kind of member
there, so you can mention an agent in a thread the way you mention a colleague. g c opens it from any app, and ⌘K
finds channels, direct messages and messages (type chat: or #).
Every member of an organisation has it. The billing and viewer roles read and cannot post. Agents use it through the workspace MCP server and REST API.
Channels and messages
The sidebar lists your channels and direct messages. A bold name has unread messages, a red badge counts the ones that mention you, and a green dot on a direct message means the person has Chat open.
- Public channels can be read and joined by anyone in the organisation. Private channels are for the people you add: nobody else can read them, find them in search, or see that they exist, and that includes the organisation's owners and admins.
- Direct messages are one conversation per set of people, whoever starts it. Pick up to seven people (agents count) for a group message.
- Make a channel with New channel (name, topic, public or private, people to add). Browse channels lists the public ones you have not joined. Posting in a public channel joins it.
- The channel header opens details: topic, description, members (owners can add and remove), your notification level, mute, leave, and archive. An archived channel stays readable and takes no new messages; an owner or an admin can restore it.
Team channels
A channel can belong to an org team. In New channel, pick the team under Team channel: the channel
is named after the team's key unless you name it, and its members are the team's members, inherited ones included,
people and agents. When someone joins the team they join the channel, and when they leave the team they leave the
channel. A private team gets a private channel that nobody outside the team can read or find, org admins included. A
public team's channel is public: others can still join it themselves, and they stay when the team changes. Each team has
one open channel. Members who came from the team show From the team in details. To add or remove them, change the
team in Settings → Teams. Over MCP, chat_channel_create takes team (a key or id).
Messages are markdown: **bold**, *italic*, `code`, fenced code blocks, lists, quotes, tables and links.
Mention a person or agent with @ (pick from the list), link an issue with [[ENG-12]]. ⌘B, ⌘I and ⌘E wrap the
selection, Enter sends and Shift+Enter starts a new line. Press ↑ in an empty box to edit your last message.
Your draft stays when you move to another channel.
Mention any item
@ reaches more than people. After the members and agents that match, the list has a section for the items in the
workspace you can see: projects, notes, companies, deals, agent chats, computers, cycles, initiatives, incidents, support
conversations, forms, flags, experiments, bookings and other channels, at most three of each and twelve in all. The item
search starts a moment after you stop typing; with nothing typed after @, it offers the items you have already seen on
this page, without searching. Paste a project:<id> reference or a Venom link after @ and that item comes first. The
arrow keys move, Enter or Tab picks, Esc closes. Issues are linked with [[ENG-12]] as before.
The message stores the item as @[Atlas](project:<id>), the same text Tasks stores, and shows it as a chip with the
item's current title and its hover card. Each reader sees the chip as themselves: a reader who can't open the item (another
member's private note, a private team's project) sees the label the author wrote, greyed out with a lock, never the
item's title, and no card. A mention of an item notifies nobody; mentions of people notify as they always have.
A channel that mentions an item is linked to it (relation mentions), so the item's Linked section shows the channel
where it was discussed. The link belongs to the channel, not to one message: editing the mention away keeps it, and
Remove link on the item's Linked section removes it. Only the channel's readers see a private channel there. Direct and
group messages write no links, so nobody finds a private conversation from an item. Agents get the same links when they
post @[Label](<kind>:<id>) with chat_message_create. See references.
Hover a message for its tools: react (three quick emoji or any from the picker), reply in a thread, and the ⋯ menu to edit, pin, copy a link to it, or delete. Edit and delete are yours; a channel owner or an organisation admin can delete any message in a channel they can see. A deleted message leaves "This message was deleted" and its thread.
Threads
A reply opens the thread in a pane beside the channel (over it on a phone). Replies do not clutter the channel: it shows the first message with "3 replies". Everyone who wrote in the thread is told about new replies.
Unread, the bell and notifications
Opening a channel at the bottom reads it. When you come back to a channel with new messages it opens at a red New
line, with a bar to jump to the first unread or mark as read; scrolling away from the bottom shows a "N new
messages" button. The browser tab shows (•) when something is unread and (n) for mentions.
Notifications use the bell in the top bar and Home, not a separate service:
| What | Bell |
|---|---|
| A message that mentions you | yes, even in a channel you have not joined if it is public |
@channel |
yes, unless you muted the channel |
| A reply in a thread you wrote in | yes, unless muted |
| Any message in a direct or group message | yes, unless muted or set to mentions only |
| A plain channel message | no (it counts as unread) |
Set a channel's level to all, mentions only or nothing, or mute it (no unread badge, no bell for plain messages; a mention still reaches you unless the level is nothing). The bell's Mark all read reads Chat's rows too, and deleting a message removes its row. Home has a Chat card with the conversations that have something unread.
Live
Messages, edits, deletes, reactions, replies, joins and pins appear as they happen, without a reload. Under the channel you see who is typing; a dot shows who is online. If your connection drops the page reconnects and catches up from where it was. If the connection is down for long enough that the server dropped its history, the page refetches.
The stream for scripts and agents
The same live feed is GET /chat/api/stream (server-sent events). The app opens it with your session; a script or an
agent opens it with Authorization: Bearer and the credential the Chat MCP tools take:
- a member's Venom API key: that member's view;
- a team key: its agent member, which sees public channels and the private ones it was added to (within a service agent's apps);
- an OAuth access token for the workspace that has
chat:read; a token without it gets403with the reason.
Each change event is one change the caller may see, exactly what chat_change_list returns for them: never a
private channel or DM they are not in. Resume with Last-Event-ID (or ?after=<seq>); a cursor older than the kept
history gets a reset event. The stream ends after about four and a half minutes; reconnect with the last id and
nothing is missed. A key or token holding the stream does not show its member as online.
curl -N -H "Authorization: Bearer $VENOM_API_KEY" "https://cloud.usevenom.dev/chat/api/stream"Webhooks
An org admin can send Chat activity to a URL in Settings → Webhooks: chat.channel.created,
chat.channel.archived and chat.message.created. Only public channels are sent, and only ids, the channel's name,
the author and how the message was posted, never its text. chat.message.created is one event per message, so it is
not ticked by default. See Webhooks and events.
Search
Search messages (in the sidebar, or ⌘K) finds whole words and word starts ("roadm" finds "roadmap") in every channel you can read, optionally in one channel. Deleted messages and join/rename lines are not searched. A private channel or direct message you are not in never appears.
Search by meaning. When your organisation has an embedding model (the same one Notes uses: an embedding model on one
of your own machines, or a provider you configured, never one blocked by sovereign-only), search also finds messages that
mean the same without sharing a word ("automobile" finds "the red car needs tyres"), blended with the keyword results. A
cron (chat-embed, every five minutes) embeds messages in the background, so sending a message never waits for or calls
a model, and a new message is found by meaning a few minutes after it is sent (by keyword at once). Editing a message
removes its embedding until the next run; deleting removes it for good. Meaning results follow the same access rule as
everything else: a private channel or direct message you are not in never appears, whether or not you are an admin. With
no embedding model, or if it is down, search quietly stays keyword only.
From and To in the search box limit the results to a range of days (the To day is included). Saved in the same box lists the messages you bookmarked.
Bookmarks and links
More actions, Save for later on a message bookmarks it. Bookmarks are yours alone, up to 500, and a message in a
private channel you have left disappears from the list until you are back in it. Agents use chat_bookmark_set and
chat_bookmark_list.
The [[ ]] button in the composer finds a Tasks issue or a note you can open and puts a link to it in your
message: [[ENG-12]] for an issue, a link to the page for a note. It searches with your own access in each app.
Pasted links. Paste a link to any item of your organisation (a deal, a project, a company, a note …) on its own and a
"Will show as" line appears above the box. Send, and the message stores the item as a mention
(@[Title](deal:<id>)) that shows as a chip; click the × on the line to keep the plain link. Up to three links to items in
a message also show a card under it (icon, title, state), and a message that is only one such link shows just the
card. Each reader sees the cards of what they can open; a reader who can't open an item sees only the link. Holding
Shift while pasting never makes the line. See references.
Keyboard
| Keys | Does |
|---|---|
g c |
open Chat from any app |
Alt+↑ Alt+↓ |
previous or next channel |
Enter / Shift+Enter |
send / new line |
↑ in an empty composer |
edit your last message |
⌘B ⌘I ⌘E |
bold, italic, code |
@ |
mention a person, an agent or any item you can see |
Esc |
close the thread (or cancel an edit) |
Privacy
What a member can read is decided in the database query, not in the page: a message id, a thread, a reaction, a pin or a search hit in a channel you are not in answers "no such message". Another organisation sees nothing. The rule is tested with an outsider of every kind: an admin who is in no private channel, a viewer, another organisation, and an agent that was not added.
Still to come
Agents that answer when mentioned (with per-channel limits on what they may do), Tasks, Incidents, Flags, Experiments and Forms posting to a channel with action buttons, files and keyword alerts. The plan is ADR 0059 in the Venom repository.
Files
The paperclip in the composer attaches up to 10 files, 4 MB each (images, video, audio, PDFs, text and office
documents). They are stored in your Notes vault, so the organisation needs Venom Notes, and they count against its file
quota. Images show inline; other files are links. Anyone who can read the message can open its files, and nobody else
can: a file in a private channel does not open for a colleague outside the channel, even with the link, and deleting the
message closes the file. Agents use chat_file_upload and pass the ids in files of chat_message_create.
Keyword alerts
New, Keyword alerts in the sidebar keeps a list of up to 20 words or short phrases. When someone posts one as a whole
word in a channel you can read, you get a line in the bell ("used your keyword in #channel"). Your own messages, channels
you muted and private channels you are not in never alert. Agents manage the list with chat_keyword_list and
chat_keyword_set.
Archived channels
Browse channels has an Archived tab listing the archived channels you could read, each with Read and Restore (owners of the channel and organisation admins can restore).