Hermes Mobile

Native Android app, installable PWA fallback, and companion server for Hermes Agent.

Hermes Mobile is not a generic LLM chat UI. It is a self-hosted, Hermes-native control surface designed for phone use: prompt by text or voice, upload files, watch tool calls live, approve actions, manage cron jobs, and get notified when long-running agent work is done.

Repo: https://git.molberg.cloud/bonzi/hermes-mobile

Status

Phase 1 skeleton is underway. The repo now contains a pnpm monorepo with a shared TypeScript package, a Fastify companion server exposing /api/health, and a Vite React mobile shell with bottom navigation. Hermes prompting, pairing/auth, persistence, realtime streams, Capacitor Android, and installer productionization are still upcoming roadmap items.

Product Goals

• Feel like a real Android app, not a web page pretending to be chat.
• Run privately on the same Linux machine as Hermes Agent.
• Keep Hermes Agent untouched where possible; operate as a companion layer above/alongside it.
• Expose Hermes-specific concepts: tool calls, sessions, jobs, generated files, approvals, background tasks.
• Make installation one-liner simple for a homelab machine.
• Stay modular enough that the app, companion server, Hermes integration, notification providers, and install scripts can evolve independently.

Planned Components

Android app (Capacitor native shell)
        |
        | HTTPS + WebSocket/SSE + native push
        v
Hermes Mobile App (native Android first, PWA fallback)
        |
        v
Hermes Companion Server
        |
        +-- Hermes CLI / Python AIAgent bridge
        +-- Hermes API server bridge
        +-- Hermes session DB reader
        +-- Hermes cron manager
        +-- Upload/file store
        +-- Push notification provider

MVP Feature Set

1. Native Android-first app shell

   • Capacitor Android wrapper around the shared web UI
   • APK/release build installable directly on Android
   • PWA/web build retained as fallback and fast dev target
   • Native-style bottom navigation, status bar, splash screen, haptics, push, share target later
   • Offline-friendly shell
   • Dark, playful visual system inspired by happy.engineering / Happy app

2. Chat / prompt screen

   • Text prompts
   • Voice note recording
   • File uploads: zip, png, jpg, pdf, txt, logs, folders later
   • Streaming responses
   • “Agent is working” state
   • Completion notification

3. Hermes-native activity timeline

   • Tool call started / finished
   • Terminal commands
   • File reads/writes
   • Browser actions
   • Home Assistant actions
   • Cron changes
   • Subagent delegation
   • Expand/collapse raw output

4. Sessions

   • Recent sessions
   • Resume session
   • Rename / pin / archive
   • Per-session attachments and generated files

5. Cron

   • List cron jobs
   • Run now
   • Pause/resume/remove
   • View last output
   • Delivery target: app notification / in-app inbox

6. Approvals

   • Push approval to phone for dangerous commands
   • Approve / deny with short audit log

7. Companion settings

   • Connect to a companion server URL
   • Pair using one-time code or passkey
   • Configure notification backend
   • View Hermes health/status

Docs

• Product Plan
• Architecture
• Design System
• Companion Server
• Mobile App Structure
• Install Strategy
• Testing Strategy
• Roadmap

Proposed Stack

Frontend:

• TypeScript
• React + Vite
• Tailwind CSS
• Zustand or TanStack Query for client state
• Capacitor Android from the start for genuine phone-app feel
• PWA/service-worker build kept as fallback and for desktop/LAN access
• Native plugins: Push Notifications, Haptics, Filesystem/Share, Status Bar, Splash Screen

Companion server:

• TypeScript Node.js initially, because file uploads, WebSocket/SSE, install scripts, and PM2/systemd are straightforward
• Fastify or Hono
• SQLite for app metadata
• Local filesystem upload store
• Python bridge subprocess or direct Hermes module calls where safe

Why not Open WebUI/LibreChat:

• They are model chat UIs.
• Hermes needs agent-native events, cron, approvals, file artifacts, process logs, sessions, and tool timelines.
• Forking a generic app would probably become more work than a clean, small purpose-built app.

One-liner install target

Final goal:

curl -fsSL https://git.molberg.cloud/bonzi/hermes-mobile/raw/branch/main/install.sh | bash

or, for local/self-hosted raw auth limitations, a release artifact URL:

curl -fsSL https://hermes-mobile.molberg.cloud/install.sh | bash

The installer should:

• Detect Hermes Agent install and config path
• Create a system user or use current user depending mode
• Install Node runtime if missing
• Download release bundle
• Create config at /etc/hermes-mobile/config.yaml or ~/.config/hermes-mobile/config.yaml
• Configure systemd service hermes-mobile-companion
• Print pairing URL / one-time setup code

Development Philosophy

• Companion server owns mobile UX state, not Hermes core.
• Hermes remains the agent runtime/source of truth for actual work.
• Every Hermes integration goes through an adapter interface so we can switch between CLI, API server, direct Python, or future Hermes-native event APIs.
• Tool-call UI should prefer structured events, but gracefully degrade to parsed CLI/API logs during early versions.
• Keep secrets out of repo. Use environment/config files and future vault integration.