Quick Start
Install notes first, or build locally and substitute ./dist/notes for notes in the examples below.
Inspect the Vault
Section titled “Inspect the Vault”notes rootnotes root --projectsThe vault defaults to ~/Documents/notes. Set NOTES to use another Git-backed vault.
List Notes
Section titled “List Notes”Run list commands from a project directory. notes prefers owner/repo from a Git remote, then falls back to local/<project> using the Git root or current directory name.
notes listnotes list --format jsonnotes list --allnotes list --tag handoffRead and Write
Section titled “Read and Write”notes read --path ~/Documents/notes/projects/owner/repo/topic.mdnotes write --path ~/Documents/notes/projects/owner/repo/topic.md --stdin < topic.mdWrites validate and refresh frontmatter, create parent directories, commit the changed note, and best-effort push the vault when it has a remote. Use notes read --json and pass its hash back with --expected-hash when an overwrite must fail if another process changed the note.
Handoffs
Section titled “Handoffs”Handoffs are normal notes tagged handoff, written as an instruction for the next session. notes handoff starts a draft with a title and a Next heading; use as much or as little structure as the work needs.
notes handoffsnotes handoffs --allnotes handoffMCP Server
Section titled “MCP Server”Start the stdio server from an MCP client:
notes mcpOpenCode exposes the tools with the server key prefix, for example notes_note_read and notes_note_write when the server is configured as notes.