agex
Docs menuNotes

Tools

Notes

Keep notes and to-dos for each project in the Notes panel, send them to agents, and let agents update them through the agex-notes skill.

The Notes panel, on the right side, holds notes and to-dos for each project, written block by block as in Notion. Most people use it as a to-do list. Press ⇧⌘N to open or close it.

Write blocks

Each line is a block you type straight into. Start a line with one of these to change its kind:

TypeTo get
[] A to-do
- A bullet
1. A numbered item
# , ## , ### A heading
> A quote
---A divider
```A code block

Type / for a list of every kind.

Markdown

Markdown shows as you write it: bold, italic, strikethrough, code, links and images, bare URLs, HTML tags and \ escapes. The markers, like ** and [...](url), hide when you leave a block and come back while you edit it.

  • Click a link or image to open it. Web links go to the browser; paths open in an editor tab.
  • Code blocks get syntax colors from their language (```rust).
  • Tables show in monospace with a bold header.
  • > [!NOTE], [!TIP] and [!WARNING] callouts get their colors.

Edit with the keyboard

KeyAction
↵Add a block
⌫At the start of a block, join it to the one above
Tab / ⇧TabIndent / outdent
⌘↵Check a to-do off
⇧⌘↑ / ⇧⌘↓Move the block up / down
⌘Z / ⇧⌘Z or ⌘YUndo / redo

Pasting several lines makes a block of each.

Drag a block by its ⋮⋮ handle to move it, or drop it on a terminal to type its text there.

Select blocks

Select whole blocks by dragging from one block into another, ⇧-clicking, pressing ⇧↑ / ⇧↓ or Esc, or pressing ⌘A twice. Then:

KeyAction
⌫Delete them
⌘C / ⌘X / ⌘VCopy, cut and paste them as markdown
Tab / ⇧TabIndent / outdent
⌘↵Check the to-dos off
⇧⌘↑ / ⇧⌘↓Move them up / down
⌘DDuplicate them
↵Go back to editing

Send notes to agents

When you select text in a block, or select whole blocks, a small bar appears with two actions:

  • Send to agent (⇧⌘↵) pastes the text into the agent you're working with. With nothing selected, ⇧⌘↵ sends the whole block you're in.
  • New … starts your default agent with the text as its first message.

The block handle's menu, or a right-click, has the same actions, plus turning a block into another kind, duplicating it and deleting it.

Pages and files

Each page is a tab in the panel.

  • Add a page with the page button.
  • Double-click a tab to rename it.
  • Right-click a tab to open the page as markdown, reveal it in Finder, clear its finished to-dos, or move it to the Trash.

Notes are plain markdown files in ~/.agex/notes/<project>/, outside your repository. The folder is named after the project's path, with each / turned into -:

/Users/me/code/app  →  ~/.agex/notes/Users-me-code-app

That way agex finds a project's notes again by itself. Each .md file is one page, and Todo.md is the default page.

How agents use your notes

When agex starts, it installs an agex-notes skill so agents can read and edit the same files:

  • In ~/.agents/skills, which most agent CLIs read, including Codex, Gemini CLI, OpenCode, Cursor, Copilot, Amp, Goose, Pi and Droid.
  • In ~/.claude/skills and ~/.kiro/skills, when Claude Code or Kiro are set up.

Ask any of them to "add this to my todos" or "do the next todo", and they edit your notes. The panel shows their edits within a second. If you're typing in a page an agent just changed, both sets of edits are merged line by line.

Terminals in agex get the AGEX_NOTES_DIR environment variable, so agents started there know the notes folder right away. To remove the skill, set agents.notes_skill to false.

What the skill tells agents

The skill asks agents to:

  • Find the notes folder from $AGEX_NOTES_DIR, or else from the project's path, walking up from their working folder to the first folder that has notes.
  • Use the existing pages, with Todo.md as the default. Create a new page only when you ask for one, and never rename or delete a page unless you ask.
  • Write - [ ] task for an open to-do and - [x] task for a finished one, keep each to-do on one line, and put details in an indented bullet under it.
  • Read the page before they start, and again just before they write it, since you may have edited it moments ago.
  • Add each to-do where it belongs, under the matching heading or at the end of Todo.md, and never add one that's already there.
  • Check a to-do off when they finish it, rather than deleting it. You clear finished to-dos from the panel.
  • Edit only the lines they mean to change, keeping your wording, order and blank lines.
  • Never put secrets in notes.