# Links to issues and PRs

Attach issues and pull requests to your todos, scratchpads and agent sessions so related work stays one click away.

Patterm only stores the link and a few labels. It never fetches the page, syncs its status or changes anything in GitHub, Gitea, Linear or any other tracker.

## Add a link

You can attach a link in three places:

- **Links** in an agent's session context sidebar
- **Links** at the bottom of a todo
- **Links** at the bottom of a scratchpad

To add one:

1. Select **Add a link** (the plus button) next to **Links**.
2. Paste the URL and press `Enter`.

The link must be an `http` or `https` URL without a username or password in it. Anything else is rejected.

A new link shows as a plain link. Its label is the host and path until you describe it.

## Describe a link

Hover a link and select the pencil (**Edit**). You can set:

| Field      | Options                                                      |
| ---------- | ------------------------------------------------------------ |
| Type       | **Link**, **Issue** or **PR**. The type sets the row's icon. |
| URL        | The address                                                  |
| Identifier | A short label such as `PAT-1` or `#42`                       |
| Title      | A readable name                                              |

The row shows the identifier as its label and the title beside it. Without an identifier, it falls back to the title, then the host. Select a row to open the link in a new tab.

Select the cross (**Detach**) to remove a link from the item. The link itself is not deleted anywhere.

> [!NOTE]
> A link belongs to the project. If the same URL is attached to several items, they share one link, so editing it changes it everywhere. A project cannot hold two links with the same URL.

## Links from agents

Agents attach links with `reference_attach`, usually after they open a pull request or find the issue they are working on. They can use `reference_list`, `reference_update` and `reference_detach` as well. For a session, an agent can leave out `target_id` and the link attaches to its own session.

Agents resolve the issue with their own tools first, such as `gh`, `tea` or a Linear MCP server, and then attach the verified URL. For example:

```json
{
    "target_type": "session",
    "url": "https://github.com/example/repo/pull/42",
    "provider": "github",
    "resource_type": "pull_request",
    "identifier": "#42"
}
```

`target_type` can be `session`, `todo` or `scratchpad`. For a todo or scratchpad, add `target_id`.

`provider` is `github`, `linear` or `generic`, and `resource_type` is `issue`, `pull_request` or `generic`. Use `generic` for Gitea and any other tracker. Attaching the same URL twice does nothing.

## Where links help

Links give you a quick route from an agent to its pull request. They also give the agent's [automatic summary](https://patterm.com/docs/conversation-history.md) more to go on, because the summary includes the titles of the session's linked references.

## Related

- [Todos and scratchpads](https://patterm.com/docs/todos-and-scratchpads.md)
- [Worktrees](https://patterm.com/docs/worktrees.md)
- [MCP tool reference](https://patterm.com/docs/mcp-tools.md)

---

This is one page of the Patterm documentation. The index of every page is at https://patterm.com/llms.txt.