hermes-mobile/README.md

# Hermes Mobile

Native Android app, installable PWA fallback, and companion server for [Hermes Agent](https://github.com/NousResearch/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

```text
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](docs/PRODUCT_PLAN.md)
- [Architecture](docs/ARCHITECTURE.md)
- [Design System](docs/DESIGN_SYSTEM.md)
- [Companion Server](docs/COMPANION_SERVER.md)
- [Mobile App Structure](docs/MOBILE_APP.md)
- [Install Strategy](docs/INSTALL.md)
- [Testing Strategy](docs/TESTING.md)
- [Roadmap](docs/ROADMAP.md)

## 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:

```bash
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:

```bash
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.