Skip to content

Commit 1d3f6bb

Browse files
backnotpropbacknotprop
authored
Add blog post about sharing plans with teammates (#160)
1 parent 35de975 commit 1d3f6bb

File tree

1 file changed

+130
-0
lines changed

1 file changed

+130
-0
lines changed

‎apps/marketing/src/content/blog/sharing-plans-with-your-team.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
---
2+
title: "Sharing Plans With Your Team"
3+
description: "How Plannotator's URL-based sharing lets teammates review and annotate agent plans together — with zero backend, zero accounts, and full privacy."
4+
date: 2026-02-18
5+
author: "backnotprop"
6+
tags: ["sharing", "collaboration", "privacy"]
7+
---
8+
9+
**Plannotator is an open-source plan review UI for AI coding agents.** It intercepts plan mode via hooks, opening a browser-based editor where you can annotate, approve, or reject plans before the agent acts. The sharing feature lets you send a plan — annotations included — to a teammate as a URL. They can review it, add their own feedback, and import it back. No backend stores anything. All data lives in the URL itself.
10+
11+
## Watch the Demo
12+
13+
<iframe width="100%" style="aspect-ratio: 16/9;" src="https://www.youtube.com/embed/a_AT7cEN_9I" title="Plannotator Demo" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
14+
15+
## The scenario
16+
17+
You're a junior developer. Claude Code just generated a plan to refactor the authentication module — new middleware, updated route guards, a migration script. It's a big change. You want a second opinion before you approve it.
18+
19+
With Plannotator, this is straightforward.
20+
21+
### 1. The plan lands in your browser
22+
23+
When Claude calls `ExitPlanMode`, Plannotator's hook intercepts it. Instead of a terminal prompt asking "Do you want to proceed?", a full review UI opens in your browser. You can read through the plan, see each section rendered as markdown, and start annotating.
24+
25+
### 2. You share the plan
26+
27+
You click **Export → Share → Copy Link**. Plannotator compresses the plan markdown and any annotations you've made into a URL hash fragment. The resulting link looks something like:
28+
29+
```
30+
https://share.plannotator.ai/#eNqrVkrOz0nV...
31+
```
32+
33+
You paste this in Slack and send it to your senior teammate.
34+
35+
### 3. Your senior reviews and annotates
36+
37+
Your senior clicks the link. The share portal — a static page with no backend — decompresses the URL hash and renders the plan with your annotations. They can now add their own feedback:
38+
39+
- **Comment** on the migration script section: "Add a rollback step"
40+
- **Replace** the session handling approach: swap JWT for HTTP-only cookies
41+
- **Delete** the unnecessary logging middleware
42+
- **Insert** a note about rate limiting on the new auth endpoints
43+
44+
Each annotation is tied to the specific text it references.
45+
46+
### 4. You import their review
47+
48+
Your senior clicks **Export → Copy Link** to share their annotated version back. You click **Export → Import Review** and paste their URL. Plannotator merges their annotations into your session, deduplicating any overlapping feedback. Now you see both your notes and theirs, with author labels distinguishing who said what.
49+
50+
### 5. You send combined feedback to Claude
51+
52+
With the merged annotations in front of you, you click **Request Changes**. Plannotator formats the combined feedback — deletions, replacements, comments, insertions — into structured markdown and sends it back to Claude Code through the hook system. Claude receives specific, actionable feedback and revises the plan.
53+
54+
## How the hook integration works
55+
56+
Plannotator plugs into Claude Code's `PermissionRequest` hook system. The configuration in `hooks.json` watches for `ExitPlanMode` events:
57+
58+
```json
59+
{
60+
"hooks": {
61+
"PermissionRequest": [
62+
{
63+
"matcher": "ExitPlanMode",
64+
"hooks": [
65+
{
66+
"type": "command",
67+
"command": "plannotator",
68+
"timeout": 345600
69+
}
70+
]
71+
}
72+
]
73+
}
74+
}
75+
```
76+
77+
When the hook fires, Plannotator reads the plan content from stdin, starts a local HTTP server, and opens the review UI. The server exposes a `/api/plan` endpoint that the browser fetches, and `/api/approve` or `/api/deny` endpoints that resolve the hook's decision. Approving sends an `allow` decision back to Claude Code. Denying sends a `deny` decision with the formatted annotation feedback as the message.
78+
79+
The feedback that reaches Claude is structured — not a vague "make it better" but specific line-level annotations:
80+
81+
```markdown
82+
## 1. Change this
83+
**From:**
84+
> JWT token stored in localStorage
85+
**To:**
86+
> HTTP-only cookie with secure flag
87+
88+
## 2. Feedback on: "logging middleware for all routes"
89+
> This is unnecessary overhead. Only log auth-related routes.
90+
91+
## 3. Add this
92+
> Add a database rollback step before the migration runs.
93+
```
94+
95+
Claude can act on each item directly.
96+
97+
## Why URL-based sharing matters
98+
99+
The sharing system uses no backend. Here's what actually happens when you click "Copy Link":
100+
101+
1. The plan markdown and annotations are serialized into a compact JSON payload
102+
2. The payload is compressed using the browser's native `CompressionStream` with `deflate-raw`
103+
3. The compressed bytes are base64url-encoded
104+
4. The result becomes the URL's hash fragment (the part after `#`)
105+
106+
The hash fragment of a URL is never sent to a server in HTTP requests — that's part of the HTTP specification. The share portal at `share.plannotator.ai` is a static page. It serves the UI, then the browser reads and decompresses the hash client-side. The server sees nothing.
107+
108+
This means:
109+
110+
- **No accounts.** No sign-ups, no OAuth, no tokens.
111+
- **No storage.** Nothing is persisted anywhere. Close the tab and the data exists only in the URL you copied.
112+
- **No tracking.** The share portal has no analytics, no cookies, no telemetry.
113+
- **Self-hostable.** If even a static page hosted by someone else isn't acceptable, you can [self-host the portal](/docs/guides/self-hosting/) and point Plannotator at it with `PLANNOTATOR_SHARE_URL`.
114+
115+
For teams working on proprietary code, this is meaningful. The plan content — which may describe internal architecture, security measures, or business logic — never leaves the URL bar. You share it over whatever channel you already trust (Slack, email, a DM) and the recipient decompresses it locally.
116+
117+
## When to use this
118+
119+
Not every plan needs a second pair of eyes. But some do:
120+
121+
- **Architectural changes** — refactors, new service boundaries, database migrations
122+
- **Security-sensitive work** — auth flows, permission models, encryption changes
123+
- **Onboarding** — a senior reviewing a junior's first few agent-assisted plans to build trust in the workflow
124+
- **Compliance** — regulated industries where changes need documented review trails (combine with [plan saving](/docs/getting-started/configuration/) to disk)
125+
126+
The sharing round-trip adds a review step without leaving the agent workflow. The junior doesn't need to copy-paste a plan into a Google Doc. The senior doesn't need to context-switch into a different tool. It all happens within the same Plannotator session that the hook opened.
127+
128+
## Try it
129+
130+
Install Plannotator as a [Claude Code plugin](/docs/getting-started/installation/), trigger a plan, and click Export → Share. Send the link to a teammate. See what they think.

0 commit comments

Comments
 (0)