🗒️ Notes

Standalone CLI and MCP server for repo-scoped Markdown notes.

notes gives humans and agents one implementation for repository notes, handoff-tagged notes, safe note reads/writes, and an MCP server for agent harnesses.

Full setup, CLI reference, MCP usage, and integration docs are published at https://notes.timmo.dev.

An optional private capture PWA sends typed or browser-transcribed notes to a configured processing queue.

The Notes Omarchy plugin provides bar access to browse, search, edit, create, and capture notes. Its source lives in omarchy-plugin/, with setup and host integration details in the Omarchy capture documentation.

Agents can use notes-cli for shell commands or notes-mcp for MCP tools. Install them with:

npx skills add timmo001/notes

Stable releases use a semver version shared by the CLI and @timmo001/effect-notes. Create a blank GitHub draft tagged with it, optionally generate its release notes, then publish it to build Linux archives, deb and RPM packages, publish the library to npm and JSR, and update repo-notes-bin in the AUR. repo-notes-git continues to track relevant changes on main.

Changes under omarchy-plugin/ are validated separately and published from main to timmo001/omarchy-notes. This publication is independent of stable Notes releases.

For local development, run mise run install and mise run build, then use dist/notes.