Read, write and search your Nextcloud Notes from inside Hermes. Notes stay plain
markdown files under /Notes in your Nextcloud account, so the Notes web app,
the phone app and Hermes all edit the same content.
- A
/notespage plus a sidebar row in Hermes Desktop (and in the browser Webapp). - Note list with search, category filter, favourite marker and excerpt.
- Editor with per-note unsaved drafts (switching notes never loses an edit),
explicit Save and
Ctrl/Cmd+S. - Save conflicts are refused, not overwritten: the backend compares the mtime the
edit started from and answers
409when someone wrote in between. - Credentials stay on the backend. The renderer only talks to
/api/plugins/notes. - A side pane:
Side panein the editor footer pins the open note to the right rail, beside the chat, the way the terminal docks. The rail has its own note picker and Save. - Follows the active theme. The UI paints no opaque surfaces: backgrounds are translucent
mixes of
--ui-text-primary, borders use--ui-stroke-secondary, text and accents use the app's own tokens. (Hermes'--ui-bg-inputis a hard-coded#fcfcfc, so anything built on the--ui-bg-*ramp looks white under a user theme; that is why this plugin avoids it.)
- Hermes Agent
>= 0.22.6(desktop plugin SDK and the/api/plugins/<name>/REST door). - A Nextcloud instance with the Notes app enabled (
occ app:install notes). - One app password for the account that owns the notes.
-
Copy this directory to
~/.hermes/plugins/notes(Windows: the Hermes home the app uses, the folder holdingconfig.yaml, for example%LOCALAPPDATA%\hermes\plugins\notes).git clone <this repo> ~/.hermes/plugins/notes
-
Enable the plugin so its backend may be imported:
hermes plugins enable notes -
Create an app password in Nextcloud (Settings, Security, "Create app password", or
occ user:auth-tokens:add --name hermes-notes <user>) and store it where only you can read it:install -m 600 /dev/null ~/.hermes/credentials/nextcloud-notes-app-password.txt printf '%s' 'THE-APP-PASSWORD' > ~/.hermes/credentials/nextcloud-notes-app-password.txt
-
Point the backend at your server, with environment variables or with
~/.hermes/notes-config.json:{ "url": "https://cloud.example.com", "user": "your-login", "insecure_tls": false } -
Make the UI load. The desktop app reads plugins from its own disk: the app-level door is
<hermes home>/desktop-plugins/notes/plugin.js, and the app copiesplugins/notes/desktop/plugin.jsthere on start. Restart the app once after installing. -
Check the backend is mounted:
curl -s -H "X-Hermes-Session-Token: $TOKEN" http://127.0.0.1:9119/api/plugins/notes/status # {"ok":true,"base_url":"...","user":"...","note_count":42,"latency_ms":90}
The dashboard hot-mounts the router on the first request, so enabling the plugin needs no dashboard restart.
| Setting | Environment | notes-config.json |
Default |
|---|---|---|---|
| Base URL | NC_NOTES_URL |
url |
http://localhost:8082 |
| Login | NC_NOTES_USER |
user |
none (the endpoint answers 503) |
| App password | NC_NOTES_TOKEN |
token_file (a path) |
~/.hermes/credentials/nextcloud-notes-app-password.txt |
| Self-signed TLS | insecure_tls: true |
off |
| Route | Purpose |
|---|---|
GET /status |
Reachability, note count, latency |
GET /notes?q=&category= |
Summaries, newest first |
GET /notes/{id} |
Full note with content |
POST /notes |
Create (title, content, category) |
PUT /notes/{id} |
Update; modified guards against clobbering |
DELETE /notes/{id} |
Delete |
- The app password is read by the backend only (
NC_NOTES_TOKENor a file). It is never sent to the renderer and never logged. - The plugin's REST namespace is scoped by construction:
ctx.rest('/notes')resolves to/api/plugins/notes/notes, behind the dashboard's own auth gate. desktop/plugin.jsimports only@hermes/plugin-sdkandreact; the runtime loader refuses anything else, andtools/checkruns the same admission lint Hermes uses (hermes_cli/plugin_validate_desktop.py) plus an ESM parse.- Deleting a note in the tab deletes the file in Nextcloud. There is no undo in this plugin.
plugin.yaml plugin metadata and optional env docs
dashboard/manifest.json declares the backend router to the dashboard
dashboard/plugin_api.py the Notes API proxy (FastAPI router)
desktop/plugin.js the /notes page: plain ESM, no build step
tools/check the repo gate (python compile, desktop lint, ESM parse)
tools/check # the gate: structure, import allowlist, dash style, node ESM parse
hermes plugins validate . # the loader's manifest + capability probetools/check is stdlib plus node only, so it works on a machine with no Hermes
checkout, and it runs in the pre-commit hook and in CI. The hook itself is not
committed; recreate it with:
printf '#!/usr/bin/env bash\nexec ./tools/check\n' > .git/hooks/pre-commit
chmod +x .git/hooks/pre-commitRelease review also runs Hermes' own admission lint, a stronger form of the import check that imports a private Hermes module, which is why it is not wired into the gate:
import sys
sys.path.insert(0, "/path/to/hermes-agent")
from pathlib import Path
from hermes_cli.plugin_validate_desktop import desktop_surface_findings
print(desktop_surface_findings(Path("desktop/plugin.js").read_text()))MIT. See LICENSE.