Quick Start
Use the notes CLI and MCP server.
Install notes first, or build locally and substitute ./dist/notes for notes in the examples below.
Inspect the Vault
notes root
notes root --projects
The vault defaults to ~/Documents/notes. Set NOTES to use another Git-backed vault.
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 list
notes list --format json
notes list --all
notes list --tag handoff
Read and Write
notes read --path ~/Documents/notes/projects/owner/repo/topic.md
notes write --path ~/Documents/notes/projects/owner/repo/topic.md --stdin < topic.md
Writes 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
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 handoffs
notes handoffs --all
notes handoff
MCP Server
Start the stdio server from an MCP client:
notes mcp
OpenCode exposes the tools with the server key prefix, for example notes_note_read and notes_note_write when the server is configured as notes.