Influxx Review Notes, Markdown Review, and Workspace Comments
After an agent changes code, Influxx gives you feedback surfaces that are not the same as Sidebar plan files. Review notes (also labeled AI notes) are line or selection comments on diffs—and on markdown in Rich mode—that you send back into a CLI agent. Workspace comments are a short sticky field on a worktree card. This guide covers the diff review loop, markdown review notes, send and resend behavior, storage boundaries, and when to use a workspace comment instead of a .md plan.
Plans live in .influxx/notes/. Fix-it feedback lives in review notes. Card reminders live in the worktree comment. Pick the surface that matches the job.
Notes surfaces compared (feedback vs plans)
Marketing copy may say “notes” for more than one UI. Storage and purpose differ—use the right tool after an agent pass.
- Sidebar notes: .influxx/notes/*.md. Best for plans bound to a workspace and for Run → agent.
- Review notes: Diffs and Source Control. Stored as worktree metadata (not git commits and not .md files). Best for line comments you send to an agent.
- Markdown review notes: Same review-note pipeline on markdown content in Rich Editor.
- Workspace comment: Worktree card meta via the worktree.comment field. Best for a sticky one-liner on a card.
- Floating notes: App userData floating-workspace. Best for scratch outside a repo—not for line-level diff feedback.
Review notes are not GitHub pull request review comments unless you also use host review separately. They are the in-cockpit “send feedback to the agent” loop: annotate the diff, send into a running or launchable agent terminal, iterate, then commit when ready. Deeper staging, PR composers, and Checks are covered in the Source Control Help topic; this article focuses on review notes, markdown review notes, and workspace comments.
Review notes on diffs
Review notes (AI notes) are line or selection comments on diffs—the core loop for telling an agent what to fix without rewriting the whole plan file.
Add and send review notes
Open a file or combined diff for the worktree (Source Control with ⌘⇧G / Ctrl+Shift+G is the usual path). Add a note on a modified-side line via the gutter or popover. See notes on the diff, in the Source Control right sidebar Notes section (with count), and on the AI notes chip on single-file headers. Use Send notes → pick All unsent notes or This file → deliver into a running agent or launch path. After send, notes mark sentAt; editing a note clears sent so it becomes unsent again and can be resent.
- Where they appear: On the diff, Source Control Notes section with count, and AI notes chip on single-file headers.
- Send scope: All unsent notes, or This file.
- After send: sentAt is set; editing clears sent so the note is unsent again.
- Actions menu: Copy all notes / Clear all notes… from the notes actions menu.
- Agent readiness: Needs a sendable agent terminal—statuses like not-ready, permission, or no-active-terminal block send.
- Storage: Worktree metadata in app data—not .md files and not git commits.
Prompt format sent to the agent
When you send review notes, Influxx shapes each comment so the CLI agent can locate the feedback:
File: path/to/file.ts
Line: 42
User comment: "Prefer early return here"
Keep comments specific and actionable. Vague notes become vague agent work. Prefer early returns, rename suggestions, test gaps, and constraint reminders over open-ended essays—those belong in Sidebar plan markdown if you need a full re-brief.
Quickstart after Run
From a cold loop: select a worktree, write a plan in Sidebar Notes, hover Run to launch the agent with a context pack, watch the CLI tab, then open Source Control. Add line-level review notes on the diff and Send notes to the agent for targeted fixes. Commit, push, and create a PR from the same panel when the diff is ready. Parallel path: New Workspace (⌘N) with the same prompt across multiple worktrees so competing implementations stay isolated—review notes stay per worktree metadata.
Markdown review notes
Markdown review notes use the same review-note pipeline, but on markdown content in Rich mode—useful when the document under review is a plan or RFC rather than application source.
Enable and use markdown review notes
Open Settings → Editor and ensure Markdown Review Notes is enabled (default on). Open a .md file in Rich Editor. Select text or add review note cards. Copy notes for an agent or send unsent notes via the same send menu used for diff review notes. Storage and send semantics match the diff pipeline: worktree metadata, sentAt on send, editing clears sent.
- Setting: Settings → Editor → Markdown Review Notes (default enabled).
- Mode: Rich Editor on a .md file (not a substitute for Source-only editing).
- Actions: Select text / add review note cards; copy for agent or send unsent notes.
- Pipeline: Same send menu and metadata storage as diff review notes.
Do not confuse markdown review note cards with wiki links or with editing the .md body itself. Wiki links ([[note#Heading]]) navigate the in-repo doc graph for humans. Review notes attach feedback metadata you send to an agent. Changing the plan body and clicking Sidebar Run again rebuilds a context pack from the file—different loop from sending line comments on a rendered selection.
Workspace comments
A workspace comment is a short sticky field on the worktree—not a document in .influxx/notes/. Use it for a one-line reminder on a card, not for agent-executable plans or line-level diff feedback.
Add or edit a workspace comment
Open Edit Worktree Details from the worktree card menu or pencil. Fill Comment (placeholder: Notes about this worktree…). Markdown-lite is supported. Save. A Workspace notes badge appears on the card when the field is non-empty. Hover the card for the rendered comment and Edit notes. The comment is searchable in the worktree palette. You can also set comments via the CLI with worktree set --comment when you automate workspace metadata.
- Field: worktree.comment on the worktree card meta.
- UI: Edit Worktree Details → Comment; badge when non-empty; hover for render + Edit notes.
- Format: Markdown-lite supported.
- Discovery: Searchable in the worktree palette.
- Not a plan file: Does not live under .influxx/notes/ and is not the Run-as-agent body.
Choosing the right feedback tool
If you are commenting on a diff for the agent to fix, use review notes in Source Control—not a freeform plan file. If you are annotating a markdown plan in Rich Editor, use markdown review notes with the setting enabled. If you need a one-line reminder on a worktree card, use the workspace comment field. If the writing is a full plan the agent should execute from scratch, use Sidebar Notes under .influxx/notes/ and Run. If the writing is not about this repo at all, use floating notes.
- Line feedback on diffs: Review notes (worktree metadata) → Send notes.
- Feedback on .md in Rich: Markdown review notes (same pipeline).
- Sticky card label: Workspace comment on the worktree.
- Bound plan + Run: Sidebar Notes → .influxx/notes/*.md.
- Out-of-repo scratch: Floating Workspace markdown.
Privacy and ownership of feedback metadata
Local-first still applies. Review notes stay in worktree metadata for the agent loop; they are not automatically published as host PR review comments. Workspace comments stay with worktree meta you control in the cockpit (and optional CLI). Sidebar plan files under a worktree can be private, shared via git, or ignored—pick intentionally. Anonymous product telemetry is a separate Settings → Privacy choice and is not note sync. Do not confuse optional usage sharing with cloud note storage.
On remote SSH worktrees, agents still run against the checkout while your cockpit remains the UI. Review notes remain the in-app feedback channel for that worktree’s diffs. Hosted PR review on GitHub or GitLab is a separate path when you open Create PR / MR composers—use both when your team wants agent iteration inside Influxx and human review on the host.
Practical checklist for agent feedback
After the first agent pass, open Source Control and annotate only the lines that matter. Send All unsent notes or This file into a ready agent terminal. If send is blocked, fix not-ready, permission, or no-active-terminal conditions first. Edit a note to clear sentAt when you need to resend corrected guidance. Use Copy all notes when you want a clipboard handoff. Clear all notes when the thread is obsolete. Keep workspace comments short; keep long acceptance criteria in Sidebar markdown; keep line fixes in review notes.
Send the line. Clear sent when you edit. Never pretend a card comment is a plan file—or that review metadata is a git commit.
Summary
Review notes (AI notes) attach line or selection comments on diffs, surface in Source Control with counts and chips, and send to an agent as File / Line / User comment prompts. Editing clears sentAt so notes can be resent; copy and clear actions live on the notes menu; send needs a ready agent terminal. Markdown review notes reuse that pipeline on Rich Editor .md content when Settings → Editor → Markdown Review Notes is enabled (default on). Workspace comments are markdown-lite sticky fields on worktree cards—searchable, badged, not .influxx/notes documents. Use each surface for its storage contract so agents, git, and humans stay aligned.
For editor modes and wiki links, see the Influxx markdown editor and wiki links Help article. For templates and PDF export, see note templates and export PDF. For Sidebar Notes, storage paths, and Run context packs, see Influxx Notes: Local Markdown, Sidebars, and Agent Context. For staging, PRs, and Checks, see Source Control in Influxx.
