All pages

Docs · Right-sidebar surfaces

Notes

Availability: macOS · Linux · Windows (the GTK sidebar's Notes pane) · cloud workspace.

The Notes tab (right sidebar, in the More menu) is a per-project markdown scratchpad. Use it for ambient project context — recent decisions, todo lists, deploy URLs, paste targets — that you want the agent to see automatically.

A __global__ bucket holds notes for windows without an active project.

Multiple notes per project

Each project can have any number of notes. The sidebar header shows the active note's title plus controls:

  • + — add a new note
  • dropdown — switch between notes
  • pencil — rename the active note
  • trash — delete it

The dropdown, pencil, and trash only appear once a project has more than one note. The footer holds the Preview / Edit toggle, the note's size against the 64 KB cap, and a Clear button.

The field under the header searches every project's notes, not just the one on screen — match a word and the results list replaces the editor. Matching is case- and diacritic-insensitive over both note bodies and titles (so cafe finds Café), each row shows the note's title, the first matching line with the match emphasized, and a count when a note matches more than once. Notes from the window's own project sort first; within a project, the note with the most matches leads.

Opening a result from another project points the pane at that project's notepad and says so in a bar above the editor, with a Back to … button. The window's own project doesn't change — only what the Notes tab is looking at — and editing there writes to that project's notes, which is what you asked for by opening it. Switching the window's project clears the detour.

Notes are also a section in Find in Project (the project-wide search window), alongside files, tab scrollback, and agent sessions. There the narrow scopes search this project's notepad and All Tabs searches every project's; clicking a hit opens it in the Notes tab.

Preview

A note with content opens rendered — headings, bold/italic, inline code, fenced code blocks, links, nested lists, tables, blockquotes, and rules. - [ ] / - [x] list items draw as checkboxes (display only — tick them by editing the source).

Press Edit in the footer to get the source. The editor stays until you leave it: clicking into a terminal, opening the note search, switching notes, or pressing Preview all bring the rendered view back. A new note opens in the editor, since there is nothing to render yet, and an empty note always shows the editor.

Outlines nest by indentation, and it doesn't matter whether you indent by two spaces, four, or tabs — depth is read from the widths your note actually uses, so a numbered sublist under a bullet keeps both markers and restarts at 1.

Tables need the | --- | delimiter row to render, and it has to have the same number of cells as the header — without that, a line containing pipes stays prose, so a shell pipeline in your notes is safe. The outer pipes are optional on either line, so Name | Value over --- | --- is a table. Columns size to their content, :--- and ---: in the delimiter row set a column's alignment, \| stays a literal pipe inside a cell, and a row with fewer cells than the header lines up under it rather than sliding left. The same renderer draws tables in the agent transcript, on kanban cards and in Help, so a table you paste between them looks the same in all four.

On Linux and Windows the Notes pane is a single scratch note with the same Edit / Preview footer and the same leave-to-render rule. It renders headings, bold/italic, code, lists and task boxes, blockquotes, link labels and rules; tables stay as their source text.

A note's title is auto-derived from the first non-empty line of its body (Apple Notes style, capped at 32 chars). Rename to give it a custom title; clearing the rename dialog reverts to the auto-derived label. The rename dialog is pinned to the project that opened it, so switching projects mid-rename can't accidentally retitle the wrong note.

Pasting

⌘V converts formatted clipboard content to markdown source. Paste an article, a wiki page, or a doc and its headings, links, bold/italic, lists, and <pre> blocks arrive as markdown the preview renders back — rather than the bare, structure-stripped text you used to get.

A clipboard with no formatting is pasted verbatim, so copying from a terminal, an editor, or another note behaves exactly as before. ⇧⌘V always pastes plain text, and right-clicking offers Paste as Plain Text whenever the clipboard has formatting to drop.

Two known rough edges. Headings are inferred from font size relative to the body text, because the converter goes through AppKit's HTML importer (which flattens <h1>–<h6> to sizes) — on a page with unusual typography a level can land off by one. Tables and blockquotes come through as plain paragraphs rather than as guessed-wrong markup.

How notes feed the agent

The agent sees notes in two ways:

  1. System prompt context block. Controlled by the Project notes toggle in the agent scope settings (on by default). The active note (with title if multiple exist) is rendered as # Project notes in the system prompt every turn. If you scope extra projects into the conversation, each contributes its own selected note as a labeled block.

  2. Direct tools. Seven dedicated tools:

    Tool Use
    notes_read Return a note for the bound project (or one named via project_id / project_name)
    notes_write Replace or append (`mode=replace
    notes_list Every note in the notepad — id, title, size, and which one is selected
    notes_add Add a note (optional text and title) and select it. Requires approval.
    notes_rename Set a note's title; an empty title reverts to the one derived from its first line. Requires approval.
    notes_delete Remove a note from the picker entirely. Requires approval.
    notes_select Bring a note to the front of the tab — what the user sees

    notes_read and notes_write follow the user's selection unless you give them an entry_id from notes_list. Passing one is usually what you want: it reaches a specific note without changing which note the user is looking at. Use notes_select only when the point is to put a note in front of them.

    To blank a note but keep it, notes_write an empty text; notes_delete removes the note itself.

Storage

Notes persist to:

~/Library/Application Support/TRMNLY/notes/notes.json

Schema is a dictionary keyed by project UUID (or __global__) of { entries: [{ id, body, customTitle? }], selectedId }. Legacy single-note-per-project files are loaded for migration.