---
title: "Projects and Repository Workspaces"
type: concept
tags: [git, architecture, agents, foundational]
created: 2026-08-24
updated: 2026-08-24
sources: ["raw/github_doc-docs-nips-nip-mp-md.md", "raw/github_doc-docs-buzz-entity-links-md.md", "raw/github_release-buzz-desktop-v0-5-18.md"]
confidence: high
buzz_version: "desktop-v0.5.18"
---

## Definition

Buzz Projects are repository-aware workspaces that group one or more NIP-34 repository announcements into a collaboration surface. NIP-MP defines the durable container as an addressable `kind:30621` event; Desktop v0.5.18 makes those containers selectable workspaces with complete repository trees, context-aware collaboration, and an overview that follows the selected section.

## How It Works

A project event is signed by one owner and references up to 64 repository coordinates (`30617:<owner>:<d>`) with `a` tags. Repositories may have different owners, one repository may appear in multiple projects, and a project may link a discussion channel. The project is metadata only: adding a repository does not transfer push, edit, delete, or administration authority, and clients must preserve each repository's own provenance.

Desktop v0.5.18 completes the repository-aware work surface: users can select project workspaces, navigate complete repository trees, and keep collaboration context and the overview synchronized with the selected section. Buzz entity links make repositories, projects, pull requests, and issues shareable as validated `buzz://` links; Desktop cards and OS deep links are implemented, while mobile cards, web PR/issue routes, cross-community links, and `link` output on get commands remain follow-ups.

## Key Parameters

- `kind:30621` — addressable project container; `(pubkey, kind, d)` is its identity.
- `a` tags — zero to 64 NIP-34 repository coordinates; duplicates are rejected.
- `buzz-channel` — optional discussion-channel metadata; it never changes repository push policy.
- `buzz-visibility` — `listed` by default or `unlisted`; an unrecognized value is treated as listed.
- Entity links — `buzz://repo`, `buzz://project`, `buzz://pr`, and `buzz://issue`; v1 is interpreted within the current community.

## When To Use

Use a Project when work spans repositories or when a team needs repository files, issues, pull requests, channels, and conversation context in one selectable workspace. Use a single repository card when no explicit project grouping is needed.

## Risks & Pitfalls

- **Permission boundary:** project membership is an assertion about grouping, never a grant over a member repository.
- Deleting a project deletes only the container; member repositories survive. Deleting a repository leaves an unavailable coordinate in the project until its owner edits the project.
- Project replacement is signer-only. A registered NIP-OA owner may delete an agent-signed project on a Buzz relay, but that owner-delete extension is not portable to vanilla NIP-09 relays.
- Entity links are community-relative in v1. Visibility in a different Desktop community does not prove the entity exists or is authorized in the current relay community.

## Related Concepts

- [[concepts/git-on-nostr]] — repository identity, signing, and storage
- [[concepts/workflows-and-automation]] — automation attached to project/channel work
- [[concepts/agents-in-buzz]] — agents collaborating inside project channels
- [[concepts/nostr-protocol-extensions]] — NIP-MP protocol catalog entry

## Sources

- `raw/github_doc-docs-nips-nip-mp-md.md`
- `raw/github_doc-docs-buzz-entity-links-md.md`
- `raw/github_release-buzz-desktop-v0-5-18.md`