Feature: open repository files directly from message links
- Dominant language
- Rust
- Stars
- 32.7k
- Forks
- 4.3k
- Avg merge
- 1d 13h
- Merged PRs (30d)
- 253
Description
## Problem
Agents frequently reference repository documents in messages using paths such as `PLANS/PLAN.md` or `GUIDES/RUNBOOK.md`. Buzz currently renders those paths as plain text, so the reader must manually open Projects, find the repository, browse the tree, and locate the file.
Raw local `file://` links are not a good solution: they are machine-specific, unsafe to accept broadly, and do not work across desktop, web, or mobile.
Observed on `block/buzz` commit `ab3af828714ab699dfc87644d234014987a4fe6b`:
- Message Markdown has first-party in-app handling for `buzz://message` links.
- Unknown schemes are otherwise passed through the default URL transform, which strips them before the anchor handler can use them.
- The Projects repository viewer can browse and display files, but it has no message-to-repository-file deep-link route.
Relevant code:
- `desktop/src/shared/ui/markdown.tsx`
- `desktop/src/shared/ui/markdown/utils.ts`
- `desktop/src/features/projects/ui/ProjectRepositoryPanel.tsx`
## Proposed behavior
Add a first-party repository-file deep link, for example:
```
buzz://repo?owner=&repo=&ref=&path=
```
Exact parameter names can follow Buzz's existing stable repository/project identifiers. A message could then contain:
```markdown
[Open the plan](buzz://repo?owner=...&repo=...&ref=main&path=PLANS%2FPLAN.md)
```
Clicking the link should navigate inside Buzz directly to the named repository and file. If a matching local checkout or snapshot is available, Buzz may use it; otherwise it should use the hosted repository view.
## Safety and failure behavior
- Accept repository-relative paths only; reject traversal and malformed identifiers.
- Do not enable arbitrary local `file://` access.
- If the repository, ref, or path is missing or inaccessible, show a clear non-destructive error and offer to open the repository root.
- Preserve existing `http(s)` and `buzz://message` behavior.
## Acceptance criteria
- [ ] Valid `buzz://repo` Markdown links remain intact through URL transformation and render as clickable links.
- [ ] Clicking a valid link opens the correct repository, ref, and file in Buzz.
- [ ] Invalid, inaccessible, or missing targets fail safely with a clear message.
- [ ] Copy/paste preserves the deep link.
- [ ] Parser, URL-transform, navigation, and missing-target cases have automated tests.
- [ ] Existing external and `buzz://message` links are unaffected.
## Why this matters
This turns agent references into one-click evidence. Humans can move from a message directly to the cited plan, guide, research note, or source file without manually reproducing the path, and the same link model can be supported across desktop, web, and mobile.
Contributor guide
Research direction
Start by reading desktop/src/shared/ui/markdown.tsx, desktop/src/shared/ui/markdown/utils.ts, and desktop/src/features/projects/ui/ProjectRepositoryPanel.tsx, then trace the existing buzz://message handling and repository navigation. Done means valid repository-file links navigate safely to the requested target, invalid targets fail clearly, copy/paste preserves the link, and the specified parser, URL-transform, navigation, and missing-target tests pass without changing existing link behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- desktop, frontend
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100