docs: initial Hermes Mobile planning scaffold
This commit is contained in:
Hermes Agent
@@ -0,0 +1,153 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user