Notes

Overview

Notes are Markdown documents scoped to your current project. They are shared across all worktrees within the same project. Use them to jot down requirements, track progress, leave instructions for agents, or capture useful output from a session. They live in Canopy's app data directory (not inside your project repo), so they never interfere with git.

Notes are auto-saved with a one-second debounce after each edit. There is no manual save step.

Opening Notes

Press Cmd+Shift+N to open the Notes Palette. This is a modal with two areas: a list sidebar on the left (with search, sort, and tag filtering) and an editor or preview pane on the right.

From the palette, you can open any note as a standalone panel in the panel grid or dock. Select a note and press Shift+Enter to open it in the panel grid, or Shift+Cmd+Enter for the dock. You can also click the external link icon in the palette header and choose between grid and dock placement.

Creating Notes

From the palette

With the Notes Palette open, press Cmd+N to create a new blank note. You can also type a search query that returns no results and a "Create [query]" prompt will appear, letting you turn the query directly into a note title.

From an agent context menu

Right-click any agent panel header (Claude, Gemini, Codex, or OpenCode) and select Create Note. Cursor panels do not currently support this action. The new note is pre-filled with the agent name, worktree name, and a timestamp. If you have text selected in that agent terminal's output at the time, it gets included as a blockquote. The note opens immediately as a panel in the panel grid.

Editing

View modes

Notes panels have a three-way toggle in the header: Edit, Split, and Preview.

• Edit shows the Markdown editor with the formatting toolbar.
• Split displays the editor and rendered preview side by side with synchronised scrolling.
• Preview shows the fully rendered Markdown in read-only mode.

The Notes Palette uses a simpler two-way toggle (Edit and Preview only) since the modal width is too narrow for a split layout.

Preview mode renders GitHub-Flavoured Markdown (GFM), which means task lists, tables, strikethrough, and syntax-highlighted code blocks all work as expected.

Formatting toolbar

The toolbar appears above the editor in both Edit and Split modes. It has two groups of buttons, separated by a divider:

Inline formatting:

• Bold — wraps the selection in **...**. Toggles off if the selection is already bold.
• Italic — wraps the selection in _..._. Toggles off if already italic.
• Code — wraps the selection in backticks. Toggles off if already a code span.

Block formatting:

• Heading — cycles through heading levels: no heading, then ##, ###, ####, then back to plain text.
• Link — inserts a [text](url) template. If text is selected, it becomes the link text with the cursor on the URL.
• List — toggles a - prefix on the current line.
• Task list — toggles a - [ ] prefix on the current line.

With no text selected, the inline buttons insert a placeholder (e.g. **bold**) and select it so you can start typing straight away.

Title and renaming

The display title for a note follows a simple fallback chain: the YAML frontmatter title field first, then the first non-empty line of the note body, then "Untitled" if both are empty.

To rename a note, double-click its title in the palette sidebar. An inline input appears where you can type the new name. Press Enter or click away to save, or Esc to cancel. Renaming updates the frontmatter title field directly.

Keyboard Shortcuts

All shortcuts use Cmd on macOS and Ctrl on Windows/Linux.

Tags

Each note can have tags stored in its YAML frontmatter. In the palette, the right-hand pane shows existing tags as pills with a remove button, plus a text input for adding new ones. Press Enter to add a tag.

Tags are normalised on save: lowercased, trimmed, and deduplicated. Bug and bug are treated as the same tag.

When any of your notes have tags, a filter row appears above the note list in the palette sidebar. It shows an "All" pill followed by one pill per unique tag. Click a tag to filter the list to only notes with that tag. Click "All" to clear the filter.

Finding and Sorting Notes

Search

The search input at the top of the palette sidebar searches across note titles, body content, and tags. Results update as you type with a short debounce. When a search returns no results, a "Create [query]" prompt appears so you can turn your query into a new note.

Sort

Click the sort icon next to the search bar to change the note ordering. Four options are available:

• Modified (newest) — the default, most recently edited notes at the top
• Created (newest) — most recently created first
• Created (oldest) — oldest notes first
• Title (A–Z) — alphabetical by display title

Your sort selection persists for the current session but resets when you quit and relaunch Canopy.

Storage and Files

Notes are stored in Canopy's user data directory at {userDataPath}/notes/{projectId}/, where projectId is a hash of your project's root path. Each note is a plain .md file with YAML frontmatter containing the title, tags, and creation timestamp.

Copy @path

Each Notes panel has a Copy @path button in the header. This copies an addressable path like @.canopy/notes/my-note.md to the clipboard. Paste this into the unified input to include the note's contents as context for an agent, the same way @file references include project files. Canopy recognizes the @.canopy/notes/ namespace and resolves it to the note's content automatically. This is the addressable namespace, not the actual on-disk storage path.

Conflict detection

If a note file is modified on disk while you have it open (for example, by another process or a sync tool), Canopy shows a "Note modified externally" warning banner. Editing is paused until you click Reload to pull in the external changes. This prevents you from accidentally overwriting updates made outside of Canopy.

Use Cases

• Task requirements — paste issue descriptions or acceptance criteria for quick reference.
• Agent instructions — draft complex prompts before pasting them into an agent session.
• Progress tracking — keep a running log of what's done and what's left.
• Code snippets — stash useful snippets or examples to reference later.
• Agent output capture — right-click an agent panel header to create a note pre-filled with the agent's context and any selected terminal text.