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:
| Type | To 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
| Key | Action |
|---|---|
| ↵ | Add a block |
| ⌫ | At the start of a block, join it to the one above |
| Tab / ⇧Tab | Indent / outdent |
| ⌘↵ | Check a to-do off |
| ⇧⌘↑ / ⇧⌘↓ | Move the block up / down |
| ⌘Z / ⇧⌘Z or ⌘Y | Undo / 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:
| Key | Action |
|---|---|
| ⌫ | Delete them |
| ⌘C / ⌘X / ⌘V | Copy, cut and paste them as markdown |
| Tab / ⇧Tab | Indent / outdent |
| ⌘↵ | Check the to-dos off |
| ⇧⌘↑ / ⇧⌘↓ | Move them up / down |
| ⌘D | Duplicate 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/skillsand~/.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.mdas the default. Create a new page only when you ask for one, and never rename or delete a page unless you ask. - Write
- [ ] taskfor an open to-do and- [x] taskfor 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.