Hermes Agent
154 lines
4.9 KiB
Markdown
154 lines
4.9 KiB
Markdown
# Hermes Mobile
|
|
|
|
Native-feeling Android-first PWA 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
|
|
|
|
Planning scaffold only. No production code yet.
|
|
|
|
## 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 / mobile browser
|
|
|
|
|
| HTTPS + WebSocket/SSE + Web Push
|
|
v
|
|
Hermes Mobile App (PWA / later Capacitor)
|
|
|
|
|
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. Mobile-first app shell
|
|
- Installable PWA
|
|
- Android-style bottom navigation
|
|
- 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 or Next.js static/PWA mode
|
|
- Tailwind CSS
|
|
- Zustand or TanStack Query for client state
|
|
- Service Worker + Web Push
|
|
- Capacitor later, only if PWA limitations matter
|
|
|
|
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.
|