How it works
Local vs. Shared Bookmarks
Historically, bookmarks broke the moment a teammate touched the file. So the whole feature stayed personal — a scratchpad, not a shared artifact. We treat that as a bug in the category, not a fact about it.
Two modes, one model
Agentic Bookmarks makes local and shared first-class, not a flag bolted on top of the same data. Local bookmarks live on your machine — perfect for the “I'm working here this week” pin you don't want to clutter the repo with. Shared bookmarks live in the repo and travel with the code: the auth boundary, the gnarly state machine, the entry point a new teammate should read first.
The split exists because the two cases have genuinely different tradeoffs. Local bookmarks can carry richer stored context — git can't bail them out if they drift, so the system invests more local data to find them again. Shared bookmarks stay leaner on purpose: every byte of stored context is a byte that can churn in a merge conflict, so the format is tuned to survive normal edits without writing back.
Local
Personal scratch state. Yours alone.
- Typical use
- Short-lived pins for the task in front of you.
- Where it lives
- Outside the repo — not committed, not shared.
- Stored context
- Richer, since git history isn't available to help recover.
- Survives edits
- Yes — repair runs against your working copy.
Shared
Team knowledge, checked into the repo.
- Typical use
- Curated landmarks the whole team — and their agents — rely on.
- Where it lives
- In the repo, versioned alongside the code it points at.
- Stored context
- Leaner footprint, tuned to avoid noisy merge conflicts.
- Survives edits
- Yes — and git history is part of how repair finds the new home.
Promote and retire
The boundary between local and shared isn't a one-way door. A bookmark that started as a private pin can be promoted to shared once it earns a label and a note worth the team's attention. A shared bookmark that's outlived its purpose can be retired back to local — or deleted — without losing the work that went into it. This is the loop that turns ad-hoc pins into durable team knowledge over time.
Repair keeps both healthy
Local and shared bookmarks both ride on the same anchor and repair machinery. When code drifts, a layered system — quick manual relocation, mechanical auto-repair, and agent-assisted repair through MCP — keeps the pin attached to the right line. Heavy investment in agent-assisted repair is what makes long-lived shared bookmarks practical: when the rare hard case appears, an agent can resolve it instead of leaving you with a silent broken pin.