References and links between items
Point at any item in the workspace (issues, notes, people, deals, incidents, tickets, forms, flags, chats, computers, Studio decks and pages and more) with one reference, open it from a pasted link, and link items across products.
Every item in your workspace has one reference, whatever product it lives in. Paste it, or the item's page link, anywhere a reference is read (⌘K, the Link box on an issue, an agent's tool call) and you get the item back: its title, its state, one line of context and its page. Items can be linked to each other across products, and each item shows everything linked to it.
The reference format
A reference is the item's kind, a colon and its id: person:0190a3b4-…, note:0190…, issue:ENG-123. These forms are
read too:
| Kind | Also read as |
|---|---|
issue (Tasks) |
ENG-123, [[ENG-123]], an old identifier after a move, /tasks/issue/ENG-123, tasks://issue/ENG-123 |
project (Tasks) |
/tasks/projects/<id> |
note (Notes) |
/globe/vault/<id>-<title>, globe://note/<id> |
person (People) |
/people/<id> |
company (People) |
/people/companies/<id> |
agent_chat (Agents) |
/agents/c/<id> |
computer (Computers) |
/computers/<id> |
artifact (Studio) |
/studio/<id>; also read as deck:<id> |
cycle (Tasks) |
/tasks/cycles/<id> |
initiative (Tasks) |
/tasks/initiatives/<id> |
deal (Funnel) |
/funnel/deals/<id> |
incident (Incidents) |
incident:INC-12, incident:12, /incidents/inc/12 (a bare INC-12 stays an issue identifier: a Tasks team may use that key) |
ticket (Support conversation) |
ticket:#42, ticket:42, /support?c=42 |
form (Forms) |
/forms/<id> |
flag (Flags) |
flag:new-checkout (the default project), flag:<project>/<key>, /flags/f/<key>?project=<project> |
experiment (Experiments) |
/exp/<id> |
booking (Calendar: a meeting someone booked with you) |
meeting:<id>, /calendar/bookings?focus=<id>; yours only |
channel (Chat: public channels and the private ones you are in) |
/chat/<id> |
Not references: form responses (they have no page of their own, the form's Responses tab lists them), chat messages (a position in a channel, not an item), direct messages (their title is the people in them), Tasks milestones and error issues (no page of their own, or no cross-product use yet).
A page link may be the full URL (https://cloud.usevenom.dev/people/…) or just the path. A bare id is tried against
every kind. After a move in from Linear, an old Linear address
(https://linear.app/<workspace>/issue/ENG-12/… or …/project/<name>-<id>) is the issue or project it became, read
through the import's map (only on the host linear.app; nothing is asked of Linear).
You only ever get back what you could open in the product itself: a private team's issue, another member's personal note, a contact someone kept private or another member's agent chat comes back as not found, never with its title. Nothing crosses from one organisation to another.
Links between items
A link says how two items relate, read from one to the other:
| Relation | Reads | Example |
|---|---|---|
relates |
relates to | an issue and the person it concerns (either way round is the same link) |
blocks |
blocks / blocked by | |
duplicates |
duplicates / duplicated by | |
mentions |
mentions / mentioned in | a note that has [[ENG-123]], an issue whose text has @Roadmap Q1 |
created_from |
created from / source of | an issue and the company that asked for it |
discussed_in |
discussed in / discusses | an issue and the note where it was decided |
worked_in |
worked in / work on | the agent chat or computer that did the work, and the issue |
To link, you must be able to see both items and change at least one of them. Linking the same pair twice changes nothing. A link goes away when either item is deleted; archiving keeps it.
Some links write themselves, because the action already says how two items relate (made by the system, or by the agent when an agent did the action; never twice):
| Action | Link |
|---|---|
| Create an issue from a support conversation | issue created_from conversation |
| Add a conversation to an issue | conversation relates issue |
| A form sends a response to Tasks | issue created_from form |
| Add a to-do to a deal | issue created_from deal |
| Incidents files a triage issue or a postmortem action item | issue created_from incident |
| Calendar files a follow-up or re-book issue after a meeting | issue created_from booking |
| People files an action item from a meeting note | issue created_from person |
| Start an agent chat on a computer | agent chat worked_in computer |
| Start an agent chat from an issue or a project (its origin) | agent chat worked_in issue / project |
| Start an agent chat from a note | agent chat discussed_in note |
| Link a note from an issue, or create a note in Notes from an issue | issue relates note |
A note linked from an issue (the issue's Notes section, tasks_note_link) is an ordinary shared link: it shows on both
items' Linked sections, in workspace_link_list and in the change feed, and workspace_item_unlink can remove it as
well as the issue's Notes section. Links made this way before were moved into the shared table by migration 0360, keeping
who made them and when.
The links the products keep themselves show in the same list: an issue's relations (blocks, related, duplicate), a
project's dependencies, the notes whose text has [[ENG-123]], and a note's own wikilinks and backlinks. Those are
changed where they live (the issue's relations, the note's text); the list names where each one is kept.
Mentions
In an issue's description or a comment, in a note, and in a Chat message, type @ and a few letters. People come
first (members and agents in Tasks and Chat, members and contacts in Notes), then a section for each kind with what matches and you can see: projects,
notes (in Tasks; in Notes @ links a note as [[Title]]), companies, agent chats, computers, cycles, initiatives, deals,
incidents, support conversations, forms, flags, experiments, bookings and chat channels, at most three of each. Paste a
reference (project:<id>) or a page link after @ and that item comes first. With nothing typed yet, the menu offers items
already shown on the page. The arrow keys move, Enter or Tab picks, Esc closes.
A mention is a chip with the kind's icon and the item's current title, so a renamed project shows its new name. Rest the
pointer on it, or move the keyboard onto it, for the item's card: the same card everywhere, the editors in Notes and Tasks
included (no browser tooltip beside it), closed with Esc or by moving away; click it to open the item (in a new tab
while you edit). If you can't see the item (a
private team's issue, another member's private note), the chip shows the label its author wrote, greyed out with a lock and
no link. It never shows the item's real title.
Saving writes a mentions link from the issue or note to each item it mentions, so the item's Linked section lists
where it was mentioned without anyone linking by hand. For an issue, the description and all its comments count together.
Remove a mention from every one of them and the link goes. A comment deleted takes its mentions with it. A mentions
link someone made by hand is never removed this way. Mentions inside code are text. Issues and notes written before this
are linked by a background pass.
An issue list filters on them too: Mentions keeps the issues that mention an item (mentions in the API's filter
tree). tasks_issue_get lists an issue's mentioned items under "Mentioned items" on the workspace MCP server and on
/tasks/mcp alone; the latter can only see Tasks items (projects, issues, cycles, initiatives), so a mentioned note or
person is left out there.
In Chat the link goes from the channel, not the message: a channel that mentions an item is linked to it, and stays linked when the message is edited or deleted (remove the link from the item's Linked section). A private channel shows there only to its members. Direct and group messages write no links. See Chat.
The stored text names the item by its stable id; the label is only a fallback:
| Where | Stored as |
|---|---|
| Tasks (descriptions, comments, the API and MCP) and Chat messages | @[Roadmap Q1](project:0190…) |
| notes | <span data-mention="project" data-id="0190…">@Roadmap Q1</span> |
Both editors read both forms, so text pasted from one product into the other keeps its mentions. Members stay
@[Name](member:<uid>) and @[Name](agent:<id>) in Tasks and notify as before; issues stay [[ENG-123]].
Paste a link
Paste a link to one of your organisation's items on its own, into an issue's description or a comment or into a Notes
note, and it turns into that item's chip. It is the same chip and the same stored text as a mention you pick from @, so
the same privacy rules and the same automatic mentions link apply.
What turns into a chip: a page address of this organisation (an issue, project, note, company, deal, chat, or any other
item with a page), project:<id> and the other <kind>:<id> references, an old linear.app address of an item moved in
from Linear, and, in Tasks only, an issue identifier such as ENG-12 on its own. An issue becomes [[ENG-12]] in both
products. A note becomes a link by id ([[note:<id>|Title]]) in Notes, so it shows in the note's backlinks, and an
@[Title](note:<id>) mention in Tasks. Every other item is a mention of its kind.
A link that is already in a note as its bare address (written before links turned into chips, or typed rather than pasted) shows as the item's chip while you read the note, through the same resolver and privacy rules; an item you can't see keeps its address, muted, with a lock. The note's text is not changed, and while you edit it the link shows as written.
How it behaves:
- The pasted text appears at once, as a link, and becomes the chip when the item is found, usually within a moment. If
you keep typing meanwhile your text stays where you typed it. Press
⌘/Ctrl+Zonce to get the plain link back. - A link you cannot open (a private team's issue, another member's private note, another organisation, an item that no longer exists), or one that takes longer than a second and a half to find, stays an ordinary link and the paste menu (Mention, Bookmark, Embed, URL) opens as before. Nothing says why.
- Several links, or a link inside a sentence, stay links. So does a link with a
#anchor, and a link to another Venom address (a staging copy, say). Shiftwith the paste (paste as plain text) never converts. Pasting inside a code block or inline code never converts.- A read-only text takes no paste.
Text written some other way (by an agent, the API, email) is not changed, but where Tasks shows it a link to an item alone on its line, or alone in a list item, is drawn as the item's chip for whoever reads it, and a link inside a sentence shows the item's card when you rest the pointer on it. A reader who cannot open the item sees the link as written.
In Chat a link to an item pasted on its own shows a "Will show as" line above the box; send it and the message stores the
mention (@[Title](project:<id>), or [[ENG-12]]), which Chat shows as the chip. Remove the line (the ×) to keep the
plain link. A message's links to items, up to three, show as a card under it (kind icon, title, state), and a message that
is nothing but one such link shows only the card. Each reader gets the card of what they can open, so a reader without
access sees just the link.
On the issue page
The issue's side panel has a Linked section under Linked notes: everything linked to the issue, grouped by kind, with the relation. Link opens a box: pick the relation, then type to search issues, projects, notes, people, companies, agent chats and computers, or paste an identifier or a page link, and choose the item. Hover a link you made to remove it.
Every row has quick actions: Copy reference (<kind>:<id>, what an agent or a tool takes), Copy link (the page URL)
and, for a link you made, Remove. Tab reaches each row, the arrow keys, Home and End move between rows, Enter opens.
Rest the pointer or keyboard focus on a row for a moment and a card opens with the item's icon, title, state and summary,
and a link to open it. The same card opens on an issue chip ([[ENG-123]]) in Notes and Tasks. An item you cannot see shows
no card.
On other pages
The same Linked section sits on a note (right pane, under Backlinks), a person (side column), a company, a Tasks project (side panel), an agent chat (under its title) and a computer (Details panel). On these it starts folded with the number of linked items on its header; click the header to open it.
In ⌘K
Paste a page link, type an identifier such as ENG-123, or a reference such as person:<id>, and ⌘K shows the item
first under Open by reference; Enter opens it. ⌘K also finds projects, companies and your agent chats by title, next
to the products' own results. See Quick search.
For agents (MCP)
On the workspace MCP server (/workspace/mcp, listed by default):
workspace_item_get{"refs": ["ENG-123", "https://…/people/…", "note:…"]}: up to 100 references in one call, eachfoundwith its card (ref,kind,id,key,title,url,state,summary), or not found. Inworkspace_batch_run,$1.idis the first item's identifier or id.workspace_link_list{"ref": "ENG-123", "kinds": ["note"], "relations": ["mentions"]}: everything linked to the item, both directions, grouped by kind and relation; each shared link carries theidto remove it with. Pages withcursorandlimit.- Mention an item in what you write (
tasks_issue_create,tasks_issue_update,tasks_comment_create,globe_note_write,globe_note_edit) as@[Label](<kind>:<id>), with thereffromworkspace_item_search: the issue or note is linked to it (relationmentions, see Mentions).tasks_issue_getlists the items an issue's text mentions under Mentioned items, only those you can see. workspace_item_link{"from": "agent_chat:…", "to": "ENG-123", "relation": "worked_in"}andworkspace_item_unlink{"id": "…"}(orfrom,to,relation).workspace_item_getalso takesinclude: ["links"](andlinks_limit, default 20, at most 50): each item comes back with its linked items, grouped by kind and relation and bounded, in the same call. An agent that picks up an issue gets the note, people, chat, computer, ticket and deal tied to it without a follow-up call for each; the answer says how many more there are (workspace_link_listpages through them). At most 10 references withinclude.workspace_item_searchtakeskinds(issue,project,cycle,initiative,note,person,company,agent_chat,computer,deal,incident,ticket,form,flag,experiment,booking,channel) and answers every kind, each hit with its reference and page link.workspace_change_listreports links too: alinkchange (created or deleted) names both items by reference, the relation and who made it, only when you can see both ends. The cursor keeps its form and gains a suffix (g12.t40.l7); a cursor without it stays valid. Resource subscriptions to a note or an issue also fire when a link touches it.
One call for an issue and everything around it:
{"name": "workspace_item_get", "arguments": {"ref": "ENG-123", "include": ["links"]}}- Issue ENG-123 Ship the resolver [In Progress] · Engineering (issue:0190…) https://…/tasks/issue/ENG-123
Linked:
discusses: Note Reference layer · Design (note:0190…) https://…/globe/vault/0190…
work on: Agent chat Build the resolver [ready] · Code chat (agent_chat:0190…) https://…/agents/c/0190…
source of: Support conversation #42 Cannot log in [open] · Casey Customer (ticket:0190…) https://…/support?c=42&view=allThese tools need no scope of their own: each product's :read scope decides which of its items an app sees, and its
:write scope whether the app may link them. The REST twins are GET /api/v1/items, and GET, POST and DELETE
/api/v1/items/links.
The browser API
The app uses GET /api/workspace/refs?r=<reference> (repeat r; or ?q=words&kinds=project,company to search),
GET /api/workspace/links?ref=<reference>, POST /api/workspace/links with {from, to, relation} and
DELETE /api/workspace/links?id=<link id>, with the console session. Changes must come from the console's own origin.
How it is built
Each product registers its kinds with a small adapter that resolves a batch of ids in one query with that product's own
visibility rules, searches titles, says whether the caller may change its items, and lists the links its own tables
hold. The shared links are one table, workspace_links (migration 0307), indexed both ways; its creates and deletes are logged by a trigger into workspace_link_changes (migration 0309) for the change feed. Adding a product's items is
an adapter and a line in the registry; the design and the plan for folding the older per-product link tables in are in
ADR 0082. The first one folded is Tasks' issue-to-note links (migration 0360); the old table stays, unread, until a later
release removes it.