---
Date: 2026-06-17
Author: Hermes
Tags: [project, remarkable, hermes, ssh, xochitl, app-development]
---

# reMarkable Hermes Communication App

## Purpose
Develop an app/workflow that lets Hermes communicate with Adolfo through the reMarkable Paper Pro: Adolfo writes on the tablet, Hermes reads/transcribes the response, then Hermes adds typed/color-coded responses back into the document or a dedicated app surface.

## Current Status
Initial SSH-based proof of concept works.

Hermes can:
- Connect to the reMarkable via SSH alias `remarkable`.
- Locate xochitl documents under `/home/root/.local/share/remarkable/xochitl/`.
- Find the document named `Hermes` via `.metadata` `visibleName`.
- Download the document files locally.
- Read handwritten replies from the generated page thumbnail/image.
- Generate a PDF-backed update containing:
  - Adolfo's handwritten response transcribed into typed text.
  - Hermes' response in a different font/color.
- Upload the updated document back to the tablet.

## Important Findings
- reMarkable documents are stored as UUID-based companion files in xochitl:
  - `{UUID}.metadata`
  - `{UUID}.content`
  - `{UUID}.pagedata`
  - optional `{UUID}.pdf` / `{UUID}.epub`
  - `{UUID}/` directory containing page `.rm` stroke/scene files
  - optional `{UUID}.thumbnails/`
- The official xochitl docs say xochitl should not be running when accessing or changing stored documents.
- Replacing a PDF while xochitl is running can update files on disk but not reliably refresh the tablet UI.
- Restarting only `rm-sync` can detect changed files and rebuild `.tree`, but did not force the visible document to refresh.
- Closing/reopening the document can help, but cached annotation/stroke layers may still appear.
- Handwriting remains visible if the page `.rm` overlay files are left in the document UUID directory.
- A reliable PDF-replacement flow was:
  1. Stop xochitl briefly.
  2. Stop rm-sync if needed.
  3. Back up the `{UUID}*` document set.
  4. Remove stale `{UUID}/` page `.rm` overlay files and old thumbnails.
  5. Upload updated `.pdf`, `.content`, `.metadata`, `.pagedata`, and thumbnail.
  6. Start xochitl again.
  7. Verify xochitl and rm-sync are active.
- This works, but stopping xochitl is disruptive. It should not be the final UX.

## Tested Document
- Visible name: `Hermes`
- UUID: `b109ab4c-f21d-4c0e-9df7-248b20dfb9b0`
- Backups made on tablet during testing:
  - `/home/root/hermes-backups/20260617-122145`
  - `/home/root/hermes-backups/20260617-122818`
  - `/home/root/hermes-backups/20260617-123411`

## References
- xochitl documentation: https://developer.remarkable.com/documentation/xochitl
- Qt/e-paper application documentation: https://developer.remarkable.com/documentation/qt_epaper
- Official Qt Quick examples: https://github.com/reMarkable/remarkable-developer-examples
- Awesome reMarkable project index: https://github.com/reHackable/awesome-reMarkable
- Toltec community package repository: https://github.com/toltec-dev/toltec
- rmkit application framework: https://github.com/rmkit-dev/rmkit
- Oxide launcher/desktop environment: https://github.com/Eeems-Org/oxide
- libremarkable Rust low-level device framework: https://github.com/canselcik/libremarkable

## Design Direction
The better long-term approach is likely a dedicated reMarkable app or Qt Quick/e-paper application rather than repeatedly replacing xochitl PDF files.

Possible directions:
- Build a Qt/e-paper app that shows a Hermes conversation surface directly on the tablet.
- Use SSH or a local bridge process to exchange messages between the tablet and Hermes.
- Keep xochitl as the handwritten input surface only if we can safely read `.rm`/scene data and write generated `.rm`/scene content without restarting xochitl.
- Prefer a non-disruptive workflow where xochitl stays running and the tablet UI refreshes naturally.

## Open Questions
- Can we generate valid `.rm`/scene stroke data for typed or rendered Hermes replies so xochitl treats it like normal ink?
- Can a custom Qt/e-paper app coexist cleanly with xochitl on Paper Pro?
- What is the best transport: SSH polling, local service, webhook, file drop, or a small tablet-side daemon?
- Can handwriting recognition be done directly from `.rm` files instead of relying on thumbnails/screenshots?
- How should message history be persisted: in xochitl, a tablet app store, or the family brain?

## Next Steps
- Study the Qt/e-paper docs and sample app path.
- Determine how to build/deploy a minimal Paper Pro Qt app.
- Prototype a simple tablet-side Hermes chat screen.
- Investigate `.rm`/scene format generation only if xochitl integration remains preferable.
