block / block/buzz

Feature: open repository files directly from message links

Open
#2,906 1 comment 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.