Skip to content

About

Nextcloud Notes inside Hermes Desktop: a /notes page and a side-pane note editor, backed by a gateway-side proxy to the Nextcloud Notes API.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

3 Commits

Folders and files

Repository files navigation

Notes: a Nextcloud Notes tab for Hermes Desktop

gate

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 /notes page 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 409 when someone wrote in between.
  • Credentials stay on the backend. The renderer only talks to /api/plugins/notes.
  • A side pane: Side pane in 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-input is 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.)

Requirements

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

Install

  1. Copy this directory to ~/.hermes/plugins/notes (Windows: the Hermes home the app uses, the folder holding config.yaml, for example %LOCALAPPDATA%\hermes\plugins\notes).

    git clone <this repo> ~/.hermes/plugins/notes
  2. Enable the plugin so its backend may be imported:

    hermes plugins enable notes
  3. 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
  4. 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
    }
  5. 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 copies plugins/notes/desktop/plugin.js there on start. Restart the app once after installing.

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

Configuration reference

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

API (mounted at /api/plugins/notes)

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

Security notes

  • The app password is read by the backend only (NC_NOTES_TOKEN or 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.js imports only @hermes/plugin-sdk and react; the runtime loader refuses anything else, and tools/check runs 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.

Layout

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)

Development

tools/check     # the gate: structure, import allowlist, dash style, node ESM parse
hermes plugins validate .   # the loader's manifest + capability probe

tools/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-commit

Release 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()))

License

MIT. See LICENSE.

About

Nextcloud Notes inside Hermes Desktop: a /notes page and a side-pane note editor, backed by a gateway-side proxy to the Nextcloud Notes API.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages