Summary

Watch for new plan files created by Claude Code's Plan Mode and automatically surface them in Kolu's UI with an inline commenting experience — similar to how Google Antigravity lets you leave scoped feedback directly on plan artifacts.

Motivation

When using Claude Code in Plan Mode (Shift+Tab × 2 or /plan), Claude generates a markdown plan file in ~/.claude/plans/ (or a project-local docs/plans/ if configured via plansDirectory in .claude/settings.json). Today, the only way to annotate the plan is Ctrl+G, which opens the file in $EDITOR — a raw text editing experience with no structure.

Antigravity solves this by treating plans as commentable artifacts (Google Docs-style inline comments). The result is three levels of feedback granularity:

1. Overall feedback — "this approach is wrong, start over"
2. Scoped feedback — "step 3 should use the existing helper, not a new one"
3. Direct editing — delete/reorder/rewrite steps

Today in Claude Code CLI, levels 1 and 3 work fine (chat input and Ctrl+G respectively). Level 2 — scoped feedback — requires you to manually locate the right line in a text editor and type a comment with enough context that Claude understands what it refers to. Kolu already has a web layer between the user and the terminal, so it can provide a proper UI for this.

Proposed behavior

Plan detection

• Watch the plan directory for new/modified .md files. The directory is one of:
  • Project-local: <project>/.claude/plans/ or the plansDirectory value from <project>/.claude/settings.json
  • User-global: ~/.claude/plans/
• When a new plan file appears (or an existing one is modified), show a non-intrusive notification in the Kolu UI — e.g. a badge on a "Plans" section in the sidebar, or a toast: "New plan: dreamy-orbiting-nebula.md"
• Clicking the notification opens the plan in a Plan Pane alongside the terminal

Plan pane

• Renders the plan markdown as structured blocks (one block per heading + its content)
• Each block is a clickable region. Clicking opens a small comment input anchored to that block
• Comments are written back to the file in a consistent format (see below)
• A "Done" button closes the pane. If $EDITOR was the trigger (see integration below), this also unblocks Claude Code

Comment format

Comments are inserted directly below the plan step they annotate, using a format Claude Code reliably interprets as feedback rather than plan content:

## Step 3: Refactor auth middleware

> [FEEDBACK]: Use the existing `verifyToken` helper from common/auth.ts
> instead of writing a new one. It already handles token refresh.

- Extract middleware into `src/middleware/auth.ts`
- Add token validation on all `/api/*` routes

Alternatively, HTML comments for invisible-in-rendered-markdown feedback:

## Step 3: Refactor auth middleware
<!-- FEEDBACK: Use verifyToken from common/auth.ts, not a new one -->

The pane should let users pick which style they prefer (visible blockquote vs hidden HTML comment). Default to blockquote since it's easier to scan.

$EDITOR integration (optional, enhances Ctrl+G)

If the user sets $EDITOR to a Kolu bridge script, Ctrl+G opens the plan in the Plan Pane instead of a terminal editor. The bridge script:

1. POSTs the file path to Kolu's server (POST /api/edit)
2. Blocks until the server responds (user clicks "Done" in the Plan Pane)
3. Exits, returning control to Claude Code which reads the modified file

This makes the file watcher and the $EDITOR bridge two entry points to the same Plan Pane UI.

Non-goals

• Rich text editing (WYSIWYG markdown) — keep it simple, render markdown blocks with comment affordances
• Plan creation — Claude Code creates plans, Kolu only annotates them
• Syncing comments back to Claude via any channel other than the file — Claude reads the file, that's the interface

Design notes

• The Plan Pane can be a split view (terminal left, plan right) or an overlay/drawer. Split view is probably better since you may want to reference the plan while Claude executes
• File watching should be debounced (plans are written incrementally as Claude generates them)
• The sidebar could grow a "Plans" section below the repo/worktree tree, listing recent plan files with timestamps

References

• [Claude Code Plan Mode docs](https://code.claude.com/docs/en/overview)
• [Antigravity artifact commenting UX](https://developers.googleblog.com/build-with-google-antigravity-our-new-agentic-development-platform/) — the interaction model to aim for
• [Thread discussing this exact UX gap](https://www.threads.com/@boris_cherny/post/DRhqRqoD6bp/) — "the best UX I've seen for plans is Antigravity's where I can add inline comments"
• [DataCamp Ctrl+G tutorial](https://www.datacamp.com/tutorial/claude-code-plan-mode) — current state of plan editing in Claude Code