---
title: PM Cross-Entity Links
---

# PM Cross-Entity Links

## What it is

Bidirectional linking between Mission Control board items and other entities
in the app -- vault notes, mind maps, diagrams, whiteboards, flowcharts,
URLs, writer documents, email threads, meetings, GitHub PRs, commits,
branches, and issues (14 entity types).

## Where to find it

The Mission Control item card shows a **Links tab** listing all linked entities
grouped by type, and each linked tool shows **backlink chips** in its header.
Users create links from a tool's toolbar via a search-and-select picker
(`PmItemPicker`), and can unlink from either side.

## How it behaves

A PM item can be linked to any of 14 entity types. GitHub entities navigate to
GitHub URLs (validated `https://github.com/` prefix) rather than activating an
in-app project. GitHub commit links can be created automatically by the commit
scanner when a commit message references an MC item (e.g. "MC-42"). GitHub PR
links are discovered by a 5-minute polling scanner that parses item references
from PR titles and bodies.

No dedicated settings. Requires `missionControlEnabled`.

## For agents

### Two write paths

1. **Core surfaces** call `PM_ITEM_LINKS_CREATE` / `_DELETE` directly via
   `useLinkToItem` and `PmItemPicker`.
2. **Plugin surfaces** (whiteboard, mindmap, flowchart) call the `boardLinks`
   bridge namespace, gated by the `boards.link` permission. The broker is
   narrower than the IPC path for security: entity type comes from the
   plugin ID (not the wire), target item must sit on a granted board, and
   a plugin can only unlink its own entity type. The reads are narrowed the
   same way: listing an entity's links drops any whose item sits on a board
   the plugin was not granted, so a granted board yields its links and an
   ungranted one yields nothing.

Both paths write the same `pm_item_links` rows and emit the same
`PM_ITEM_LINKS_CHANGED` push. The 14 entity types are defined in
`LINK_ENTITY_TYPES`.

### IPC channels

Defined in `src/shared/ipc-channels/pm.ts`:

- `PM_ITEM_LINKS_LIST` -- list links for an item
- `PM_ITEM_LINKS_CREATE` -- create a link
- `PM_ITEM_LINKS_DELETE` -- soft-delete a link
- `PM_ITEM_LINKS_FOR_ENTITY` -- reverse lookup (links from entity side)
- `PM_ITEM_LINKS_SEARCH_ITEMS` -- search items for the picker

All are desktop-only (`BLOCKED_CHANNELS`).

- Contract: `pm-cross-entity-link-contract.md`.

## Related

The items being linked are described in [mission-control.md](mission-control.md), the parent system
for this area. Two neighbours worth knowing: [pm-session-link.md](pm-session-link.md) connects a
running session to an item rather than a document or a code artifact, and
[pm-search-integration.md](pm-search-integration.md) makes those same items findable from global
search. The tools on the other end of a link are covered by [kms.md](kms.md) for vault notes,
[mindmap.md](mindmap.md), [whiteboard.md](whiteboard.md) and [flowchart.md](flowchart.md) for the
plugin surfaces, and [ai-writer.md](ai-writer.md) for writer documents. Every page in this library is
listed in [INDEX.md](INDEX.md).