modem-dev · benvinegar · May 10, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,8 @@ All notable user-visible changes to Hunk are documented in this file.
 
 ### Added
 
+- Added session-persistent user-authored inline notes with `i` to draft/save notes and `hunk session note ...` commands for agent readback.
+
 ### Changed
 
 ### Fixed

diff --git a/src/core/cli.ts b/src/core/cli.ts
@@ -8,6 +8,7 @@ import type {
   LayoutMode,
   PagerCommandInput,
   ParsedCliInput,
+  ReviewNoteSource,
   SessionCommentApplyItemInput,
 } from "./types";
 import { resolveBundledHunkReviewSkillPath } from "./paths";
@@ -596,8 +597,8 @@ async function parseSessionCommand(tokens: string[]): Promise<ParsedCliInput> {
           "  hunk session get --repo <path>",
           "  hunk session context <session-id>",
           "  hunk session context --repo <path>",
-          "  hunk session review <session-id> [--include-patch]",
-          "  hunk session review --repo <path> [--include-patch]",
+          "  hunk session review <session-id> [--include-patch] [--include-notes]",
+          "  hunk session review --repo <path> [--include-patch] [--include-notes]",
           "  hunk session navigate (<session-id> | --repo <path>) --file <path> (--hunk <n> | --old-line <n> | --new-line <n>)",
           "  hunk session navigate (<session-id> | --repo <path>) (--next-comment | --prev-comment)",
           "  hunk session reload (<session-id> | --repo <path> | --session-path <path>) [--source <path>] -- diff [ref] [-- <pathspec...>]",
@@ -607,6 +608,9 @@ async function parseSessionCommand(tokens: string[]): Promise<ParsedCliInput> {
           "  hunk session comment list (<session-id> | --repo <path>)",
           "  hunk session comment rm (<session-id> | --repo <path>) <comment-id>",
           "  hunk session comment clear (<session-id> | --repo <path>) --yes",
+          "  hunk session note list (<session-id> | --repo <path>) [--source <ai|agent|user>]",
+          "  hunk session note get (<session-id> | --repo <path>) <note-id>",
+          "  hunk session note rm (<session-id> | --repo <path>) <note-id>",
         ].join("\n") + "\n",
     };
   }
@@ -647,19 +651,23 @@ async function parseSessionCommand(tokens: string[]): Promise<ParsedCliInput> {
       .option("--json", "emit structured JSON");
 
     if (subcommand === "review") {
-      command.option(
-        "--include-patch",
-        "include raw unified diff text for each file in review output",
-      );
+      command
+        .option("--include-patch", "include raw unified diff text for each file in review output")
+        .option("--include-notes", "include live review notes in review output");
     }
 
     let parsedSessionId: string | undefined;
-    let parsedOptions: { repo?: string; includePatch?: boolean; json?: boolean } = {};
+    let parsedOptions: {
+      repo?: string;
+      includePatch?: boolean;
+      includeNotes?: boolean;
+      json?: boolean;
+    } = {};
 
     command.action(
       (
         sessionId: string | undefined,
-        options: { repo?: string; includePatch?: boolean; json?: boolean },
+        options: { repo?: string; includePatch?: boolean; includeNotes?: boolean; json?: boolean },
       ) => {
         parsedSessionId = sessionId;
         parsedOptions = options;
@@ -678,6 +686,7 @@ async function parseSessionCommand(tokens: string[]): Promise<ParsedCliInput> {
         output: resolveJsonOutput(parsedOptions),
         selector: resolveExplicitSessionSelector(parsedSessionId, parsedOptions.repo),
         includePatch: parsedOptions.includePatch ?? false,
+        includeNotes: parsedOptions.includeNotes ?? false,
       };
     }
 
@@ -1162,6 +1171,109 @@ async function parseSessionCommand(tokens: string[]): Promise<ParsedCliInput> {
     throw new Error("Supported comment subcommands are add, apply, list, rm, and clear.");
   }
 
+  if (subcommand === "note") {
+    const [noteSubcommand, ...noteRest] = rest;
+    if (!noteSubcommand || noteSubcommand === "--help" || noteSubcommand === "-h") {
+      return {
+        kind: "help",
+        text:
+          [
+            "Usage:",
+            "  hunk session note list (<session-id> | --repo <path>) [--file <path>] [--source <ai|agent|user>]",
+            "  hunk session note get (<session-id> | --repo <path>) <note-id>",
+            "  hunk session note rm (<session-id> | --repo <path>) <note-id>",
+          ].join("\n") + "\n",
+      };
+    }
+
+    if (noteSubcommand === "list") {
+      const command = new Command("session note list")
+        .description("list inline review notes")
+        .argument("[sessionId]")
+        .option("--repo <path>", "target the live session whose repo root matches this path")
+        .option("--file <path>", "filter notes to one diff file")
+        .option("--source <source>", "filter to ai, agent, or user notes")
+        .option("--json", "emit structured JSON");
+
+      let parsedSessionId: string | undefined;
+      let parsedOptions: { repo?: string; file?: string; source?: string; json?: boolean } = {};
+      command.action((sessionId: string | undefined, options) => {
+        parsedSessionId = sessionId;
+        parsedOptions = options;
+      });
+
+      if (noteRest.includes("--help") || noteRest.includes("-h")) {
+        return { kind: "help", text: `${command.helpInformation().trimEnd()}\n` };
+      }
+
+      await parseStandaloneCommand(command, noteRest);
+      if (
+        parsedOptions.source !== undefined &&
+        parsedOptions.source !== "ai" &&
+        parsedOptions.source !== "agent" &&
+        parsedOptions.source !== "user"
+      ) {
+        throw new Error("Note source must be one of ai, agent, or user.");
+      }
+
+      return {
+        kind: "session",
+        action: "note-list",
+        output: resolveJsonOutput(parsedOptions),
+        selector: resolveExplicitSessionSelector(parsedSessionId, parsedOptions.repo),
+        filePath: parsedOptions.file,
+        source: parsedOptions.source as ReviewNoteSource | undefined,
+      };
+    }
+
+    if (noteSubcommand === "get" || noteSubcommand === "rm") {
+      const command = new Command(`session note ${noteSubcommand}`)
+        .description(
+          noteSubcommand === "get"
+            ? "show one inline review note"
+            : "remove one user-authored inline review note",
+        )
+        .argument("[sessionIdOrNoteId]")
+        .argument("[noteId]")
+        .option("--repo <path>", "target the live session whose repo root matches this path")
+        .option("--json", "emit structured JSON");
+
+      let parsedSessionIdOrNoteId: string | undefined;
+      let parsedNoteId: string | undefined;
+      let parsedOptions: { repo?: string; json?: boolean } = {};
+      command.action(
+        (sessionIdOrNoteId: string | undefined, noteId: string | undefined, options) => {
+          parsedSessionIdOrNoteId = sessionIdOrNoteId;
+          parsedNoteId = noteId;
+          parsedOptions = options;
+        },
+      );
+
+      if (noteRest.includes("--help") || noteRest.includes("-h")) {
+        return { kind: "help", text: `${command.helpInformation().trimEnd()}\n` };
+      }
+
+      await parseStandaloneCommand(command, noteRest);
+      const resolvedNoteId = parsedOptions.repo
+        ? (parsedNoteId ?? parsedSessionIdOrNoteId)
+        : parsedNoteId;
+      const resolvedSessionId = parsedOptions.repo ? undefined : parsedSessionIdOrNoteId;
+      if (!resolvedNoteId) {
+        throw new Error(`Pass a note id to session note ${noteSubcommand}.`);
+      }
+
+      return {
+        kind: "session",
+        action: noteSubcommand === "get" ? "note-get" : "note-rm",
+        output: resolveJsonOutput(parsedOptions),
+        selector: resolveExplicitSessionSelector(resolvedSessionId, parsedOptions.repo),
+        noteId: resolvedNoteId,
+      };
+    }
+
+    throw new Error("Supported note subcommands are list, get, and rm.");
+  }
+
   throw new Error(`Unknown session command: ${subcommand}`);
 }
 

diff --git a/src/core/types.ts b/src/core/types.ts
@@ -3,6 +3,23 @@ import type { FileDiffMetadata } from "@pierre/diffs";
 export type LayoutMode = "auto" | "split" | "stack";
 export type VcsMode = "git" | "jj";
 
+export type ReviewNoteSource = "ai" | "agent" | "user";
+
+export interface ReviewNote {
+  id: string;
+  source: ReviewNoteSource;
+  filePath: string;
+  hunkIndex?: number;
+  oldRange?: [number, number];
+  newRange?: [number, number];
+  body: string;
+  title?: string;
+  author?: string;
+  createdAt: string;
+  updatedAt?: string;
+  editable: boolean;
+}
+
 export interface AgentAnnotation {
   id?: string;
   oldRange?: [number, number];
@@ -12,8 +29,11 @@ export interface AgentAnnotation {
   tags?: string[];
   confidence?: "low" | "medium" | "high";
   source?: string;
+  title?: string;
   author?: string;
   createdAt?: string;
+  updatedAt?: string;
+  editable?: boolean;
 }
 
 export interface AgentFileContext {
@@ -119,6 +139,7 @@ export interface SessionReviewCommandInput {
   output: SessionCommandOutput;
   selector: SessionSelectorInput;
   includePatch: boolean;
+  includeNotes?: boolean;
 }
 
 export interface SessionNavigateCommandInput {
@@ -200,6 +221,31 @@ export interface SessionCommentClearCommandInput {
   confirmed: boolean;
 }
 
+export interface SessionNoteListCommandInput {
+  kind: "session";
+  action: "note-list";
+  output: SessionCommandOutput;
+  selector: SessionSelectorInput;
+  filePath?: string;
+  source?: ReviewNoteSource;
+}
+
+export interface SessionNoteGetCommandInput {
+  kind: "session";
+  action: "note-get";
+  output: SessionCommandOutput;
+  selector: SessionSelectorInput;
+  noteId: string;
+}
+
+export interface SessionNoteRemoveCommandInput {
+  kind: "session";
+  action: "note-rm";
+  output: SessionCommandOutput;
+  selector: SessionSelectorInput;
+  noteId: string;
+}
+
 export type SessionCommandInput =
   | SessionListCommandInput
   | SessionGetCommandInput
@@ -210,7 +256,10 @@ export type SessionCommandInput =
   | SessionCommentApplyCommandInput
   | SessionCommentListCommandInput
   | SessionCommentRemoveCommandInput
-  | SessionCommentClearCommandInput;
+  | SessionCommentClearCommandInput
+  | SessionNoteListCommandInput
+  | SessionNoteGetCommandInput
+  | SessionNoteRemoveCommandInput;
 
 export interface VcsCommandInput {
   kind: "vcs";

diff --git a/src/hunk-session/bridge.ts b/src/hunk-session/bridge.ts
@@ -7,6 +7,7 @@ import type {
   NavigatedSelectionResult,
   ReloadedSessionResult,
   RemovedCommentResult,
+  RemovedUserNoteResult,
 } from "./types";
 
 export interface HunkSessionBridgeHandlers {
@@ -33,6 +34,7 @@ export interface HunkSessionBridgeHandlers {
     options?: { sourcePath?: string },
   ) => Promise<ReloadedSessionResult>;
   removeLiveComment: (commentId: string) => RemovedCommentResult;
+  removeUserNote?: (noteId: string) => RemovedUserNoteResult;
 }
 
 /** Build the app-facing bridge handler the generic broker client calls into for Hunk commands. */
@@ -72,6 +74,11 @@ export function createHunkSessionBridge(handlers: HunkSessionBridgeHandlers) {
           });
         case "remove_comment":
           return handlers.removeLiveComment(message.input.commentId);
+        case "remove_user_note":
+          if (!handlers.removeUserNote) {
+            throw new Error("This Hunk session cannot remove user notes.");
+          }
+          return handlers.removeUserNote(message.input.noteId);
         case "clear_comments":
           return handlers.clearLiveComments(message.input.filePath);
       }