Skip to content
Docs menu

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.

View .md

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.

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 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+Z once 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).
  • Shift with 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, each found with its card (ref, kind, id, key, title, url, state, summary), or not found. In workspace_batch_run, $1.id is 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 the id to remove it with. Pages with cursor and limit.
  • 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 the ref from workspace_item_search: the issue or note is linked to it (relation mentions, see Mentions). tasks_issue_get lists 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"} and workspace_item_unlink {"id": "…"} (or from, to, relation).
  • workspace_item_get also takes include: ["links"] (and links_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_list pages through them). At most 10 references with include.
  • workspace_item_search takes kinds (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_list reports links too: a link change (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=all

These 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.