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.
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.