Notes

Notes are plain Markdown documents that live next to your agents. Write a plan, break it into to-dos, and send any to-do to an agent. The agent gets the note as context, its progress shows under the to-do, and it can write its findings back into the note.

#Create a note

• Press ⌥⌘N, or run New Note from the command palette.
• Or choose Note in the sidebar's new-session menu.

A note is a session. It sits in the sidebar with your agents and terminals, and it sorts, pins, archives and nests the same way. An agent started from a note appears as the note's child. The first line is the title; a note with no title shows as "Untitled".

#Write

Type / for the block menu or @ to mention something. Markdown shortcuts also work as you type.

The / menu adds Callout, Table and Image. Callouts are stored as GitHub alerts such as > [!NOTE]. Tables are GFM tables; ⌃↵ opens the table menu for inserting rows and columns, alignment and deleting. Pasted or dropped images are saved next to the note, up to 25 MB each.

Tick a to-do with ⌘↵. Move a block with ⌥⇧↑ / ↓. The full list is in Keyboard shortcuts.

#Mentions and links

Type @ to mention a diri session or another note. A mention is stored as an ordinary Markdown link, for example [@Release plan](diri://note/<id>), and shown as a chip. Pasted links to tools such as GitHub pull requests, Linear, Figma, Notion, Google Docs and Slack show as chips too. diri does not fetch their contents.

#To-dos

Press ⌃⌘T, or click To-dos in the sidebar, to see every open to-do across your notes. Ticking one there writes it back to its note.

#Start an agent from a to-do

1. Put the caret on an open to-do, or hover it, and click Start (⌃⌘↵).
2. Under Start with, choose an agent. The default is marked.
3. What the agent gets shows the exact brief before you send it.

The brief contains the to-do, the indented lines under it, the heading section it sits in, short excerpts of notes it mentions, the sessions it mentions with their status, and any earlier attempt's report. It is capped at 24 KB. The agent is told to report back and not to tick the to-do itself.

#Follow it live

The new session's chip is added to the to-do, and a status line appears under it:

This status comes live from the Engine and is never written into the file. Each attempt adds one more chip, newest last. The agent's session shows the note's title above its own; click it to jump back to the to-do.

When you are happy with the work, tick the to-do. If the agent is still running, diri asks whether to Tick and stop the agent or Tick, keep it running.

#How agents write back

diri's MCP server gives agents tools for notes. Agents are asked to add short entries (decisions, findings, blockers, results, links) rather than progress chatter, to prefer adding over rewriting, and never to delete silently.

A report from a to-do's own agent lands as a bullet under that to-do. Anything else goes into an ## Updates section, created if missing, with the agent's chip and a timestamp. An agent started from a note may only write to that note or to notes that mention it.

#From the command line

The dirijor note command does the same from any shell:

dirijor note "Ship the beta"                    # quick note; first line is the title
dirijor note todo "Write release notes"         # add to this project's To-dos note
dirijor note list --all
dirijor note show "Release plan"
dirijor note check "Release plan" "Write release notes"
dirijor note append "Release plan" "Beta is out"
dirijor note history "Release plan"
dirijor note path                               # print the notes folder

Run dirijor note help for every subcommand and flag, including add --pin --open, edit --old --new, replace-section and link.

#Search

Press ⇧⌘F for Search notes. It searches titles and the whole body, including to-dos, table cells and mention labels, across live and archived notes. Every word you type must appear. Archived notes show dimmed, and opening one unarchives it. The command palette also shows up to three matching notes while you type.

#Version history

diri keeps earlier versions of every note. With a note open, run Version History… from the command palette. Pick a version to preview it, then Restore This Version…. The text you replace stays in history.

Each note keeps up to 200 versions or 20 MB. Only you can restore a version; agents can read history but not restore it.

#Edits from elsewhere

Agents, the CLI and other editors can change a note while you have it open. With no unsaved typing, the note simply reloads. Otherwise diri merges block by block: additions from both sides are kept, and if both changed the same block your text wins while an outside tick or chip is kept. The losing edit stays in version history.

#Where notes live

Each note is one Markdown file with a small front matter block.

You can edit the files with any editor; diri notices and records a version. Images live in assets/, history in .history/, and deleted notes in .trash/ inside the same folder.