Comments And The ✦ AI Menu

When you select text, Iliad shows two actions, Comment and ✦ AI, next to the selection. Comments are saved as a plain Markdown file next to your document, so an outside agent can read them.

Comments

Select a passage and choose Comment (or press ⌘⇧M), type the comment, and save it. The passage gets a soft blue wash.

Comments for name.md are stored in name.comments.md in the same folder. Each entry quotes the passage and then the comment.

<!-- iliad:comment id=c7f2 -->
> the exact passage the comment refers to

What you want done there.

---

The file is created with your first comment and deleted when you remove the last one.
Outside agents read the file, change the document at each quoted passage, and delete the entries they handled. When an entry disappears from the file, its wash disappears from the document.
If the passage a comment points to was rewritten, the comment becomes detached. Iliad shows "N detached comments" in the editor toolbar, where you can read and delete them.

Comments In The Margin

Press ⌃⌘M, or Comments at the top right of the window, to show every comment in the right margin, written out beside its passage. Press it again to hide them. Iliad remembers your choice.

Point at a comment to see its passage and a small × that deletes it.
Click a comment to open it with Edit and Delete.
When a paragraph has many comments, long ones end in "…" and the rest fold into "+2 more". Click either to read them in full.
The margin needs a wide enough window. In a narrow one, comments show on hover as before.

Comments From Your Agent

An agent such as Claude Code or Codex can leave comments too, for example when you ask it for feedback instead of edits. Its comments are marked ✦ and carry by=ai in the comments file:

<!-- iliad:comment id=ai-k3v9 by=ai -->
> the exact passage

Feedback for you.

They are feedback for you, not instructions: when you ask an agent to address your comments, it leaves these alone. With the margin hidden they leave no mark in your text. Delete them when you are done.

The Comments File In The Tree

The comments file is a companion of its document. In the file tree it appears as Comments · N under the document you have open. When you rename, move, duplicate, or trash a document in Iliad, its comments go with it.

Names ending in .comments.md are reserved for comments files. Iliad will not create or rename a document to one of them.

Writing notes were removed in v0.4.0. Comments are now how you tell your agent what you want. An existing name.notes.md file is left as it is and now shows up as an ordinary document.

Select text and press ⌘↵ or click ✦ AI. Pick an action with ↑/↓ and Enter, or type your own instruction in "Tell the AI what to do…".

Rewrite makes the text read more clearly and naturally, with the same meaning.
Expand adds detail and development, with the same point and voice.
Shorten uses fewer words (⌘⇧J runs it directly).
Summarize keeps only the key points.
Turn into a list makes a Markdown bulleted list, one idea per item.

The result appears in place, over the selection. Tab accepts and Esc rejects. Only the selection changes, and nothing is written until you accept. If the document changes while a result is pending, Iliad discards the stale result instead of applying it to the wrong text.

Limits

The AI is included free, with a daily limit shared with autocomplete, or you can use your own Groq key (Writing assists → Use my key). Only the selection and your instruction are sent, and only when you pick an action. See Privacy.
Selections are capped at 4000 characters and typed instructions at 1000 characters.
The ✦ AI menu works on the current selection only, not across documents. Use an outside agent for larger work.
Comments are disabled while the open file is itself a comments file.
Comments are for you and your agent, not for multi-user collaboration.

This page is generated from comments-tighten-edit-selection.md, which you can also read as Markdown.