Notes

notes stores Markdown files in a Git-backed vault and opens an interactive browser when run without a command. The default vault is ~/Documents/notes; set NOTES to use a different path. DOT_NOTES_DIR is still read as a compatibility fallback when NOTES is unset.

Browse

notes
notes --all

The TUI is a document-first browser. Wide terminals use a 35/65 split between the note list and Markdown preview. When both pane minimums no longer fit, it switches to a one-pane master/detail layout while preserving each pane’s selection and scroll position. Terminals below the compact floor show a stable resize screen instead of a broken workspace.

The preview keeps the title and priority summary visible above the document. Metadata is expanded by default in split mode and collapsed in master/detail mode. Toggle it with i; your choice persists for the rest of the TUI session. The bottom command bar only shows commands relevant to the active pane, while ? opens the complete grouped shortcut reference.

Useful controls:

Key	Action
up / down	Move through notes
Tab	Switch between list and preview
Enter	Open the selected note preview
/	Search note names, tags and summary
s	Cycle sorting
v	Toggle current repo/all repos
a / A	Create a note in editor/visual
e / E	Edit in editor/visual
o	Open the full note in OpenCode
O	Plan from the full selected note
d	Delete after confirmation
r	Refresh
i	Toggle preview metadata
?	Open grouped keyboard help
Esc / Backspace	Exit or go back

Editor actions are launched through Bash and must stay attached until editing finishes. Set EDITOR for terminal editing and use a waiting visual command such as VISUAL="code --wait" for A and E. Both modes fall back to Neovim when no editor is configured.

The o and O actions require OpenCode. O adds portable built-in planning instructions to the full selected note context.

OpenCode runs from the selected note’s source checkout, including when Notes was opened from another directory or with --all. Notes remembers exact checkout paths as machine-local state under $XDG_STATE_HOME/notes; paths are not written into portable note files. A local note whose remembered directory no longer exists keeps the Notes process’s current directory.

Layout

Repository notes live under:

{vault}/projects/{owner}/{repo}/{slug}.md

The {owner}/{repo} segment is resolved from the current Git repository’s remote URL. notes prefers origin, then upstream, then the first remote, so a fork keeps its notes under its own owner. To use another remote for one checkout, set it in that checkout’s Git config, for example git config notes.remote upstream. When no usable remote exists, notes use projects/local/{project}. The project name comes from the Git worktree root, or from the current directory outside Git.

Frontmatter

Notes are ordinary Markdown files with YAML frontmatter:

---
repo: owner/repo
date: 2026-07-06T12:00:00+01:00
name: Useful Note
description: One-line summary.
tags: [research, handoff]
priority: medium
---

name, description, tags, and priority are used for listings. Writes validate the frontmatter and refresh date: automatically.

The body is free-form Markdown. A few paragraphs with no headings is a perfectly good note.

Safety

Read, write, and delete operations are restricted to physical Markdown files under projects/{owner}/{repo}. Symlinks, special files, malformed project identities, and paths elsewhere in the vault are rejected. Writes use atomic replacement, and draft creation never overwrites an existing filename.

Before a mutation, notes refuses an existing staged index and rebases safely onto the configured upstream. Mutations are serialized across processes, committed to the vault Git repo, and then pushed when a remote exists. Editor sessions hold the same transaction lock until the resulting note is validated and committed. A commit or push failure is reported as partial success because the local file change has already completed.

notes read --json and MCP note_read return a SHA-256 revision. Pass it to notes write --expected-hash or MCP note_write.expectedHash to reject a stale overwrite.

Listing

notes list
notes list --format json
notes list --all
notes list --tag research

The JSON form returns structured note metadata for scripts and plugins.