4.8 KiB
4.8 KiB
00 — Overview
Vision
A native, Telegram-quality chat experience for a personal hermes-agent:
install an app on your phone (and a desktop app on your PC), pair it to your
running hermes gateway, and talk to your agent with streaming replies,
visible reasoning, structured tool activity, channels/threads, media, search,
and push notifications — with cron jobs able to post into any channel you
create.
Goals
- Native feel. Real Android app (Kotlin/Compose), not a WebView. Desktop app that is the same app, resized for a big screen.
- First-class gateway citizen. The app is a hermes messaging platform, so
everything the gateway already does "just works": slash commands, cron
delivery,
send_messagerouting, coexistence with Telegram/Discord/etc. - Full agent transparency. Streaming text, reasoning shown before the answer, structured tool events (the app chooses how much to show), and intermediate assistant beats.
- Organized by default. A default chat with optional threads, plus user-created channels that cron jobs can target.
- Reachable anywhere. Live over a WebSocket; background push via FCM (primary) or ntfy (fallback).
In scope (v1)
Everything in the feature checklist below.
Out of scope / stretch (v1)
- Standalone-cron delivery while the gateway process is fully down — best-effort FCM/ntfy only (the outbox is served by the running gateway).
- Multi-user / group chat — this is a personal 1-user agent.
- End-to-end encryption — transport security (WSS) only.
- iOS — Android + Desktop only (the protocol is transport-agnostic, so an iOS client is a future port, not a v1 goal).
Feature checklist → where it's handled
| Requirement | Gateway plugin | App |
|---|---|---|
| Input box, auto-grow (max height) | — | Compose TextField + bounded heightIn |
| Menu button → all slash commands | Dispatches /…; serves command catalog |
Bottom-sheet menu + / autocomplete |
| Tool output (app decides how much) | Emits structured tool events | App setting: everything / truncated / nothing |
| Reasoning shown before message | Captures + splits reasoning | Collapsible "Reasoning" block above message |
| Intermediate messages | Forwards Commentary events |
Distinct dimmed bubble |
| Threading + channels; default chat; user channels for cron | chat_id/thread_id model; cron deliver=iris:<chat>[:<thread>] |
Channel list, thread toggle, "new channel" |
| Search ("everywhere" / "this chat/channel") | FTS5 session search bridge | Search UI + scope toggle |
| Attach media (music/video/images/docs) | Inbound cache; outbound send_* |
Pickers + chunked upload + preview |
| Push notifications | FCM (primary) / ntfy (fallback) | FCM token / ntfy topic + notification service |
| Live playback of AI-sent music/video | Serves media bytes over WS | ExoPlayer inline player |
Locked decisions (from planning)
| Decision | Choice |
|---|---|
| Desktop app tech | Compose Multiplatform (shares Android code; "tweaked" for big screen) |
| Push backend | Both — FCM primary, ntfy fallback (IRIS_PUSH_BACKEND) |
| Media transport | Over the WebSocket (chunked binary frames; no extra Python deps) |
| Phone default layout | User-toggleable, single-pane default (auto two-pane on large screens) |
Disclaimers (hard rules)
hermes-agent/is a read-only research reference. It lives next to this folder for study only. It is git-ignored and must never be committed, pushed, or included in any artifact. Our plugin is installed into a live hermes home (~/.hermes/plugins/iris); we never edit hermes core files.- ADB is available and a device is connected (
a5ca2a4b, Xiaomi MIX 2S, Android 10 / API 29). Useadb install/adb logcat/adb shell am startto install, launch, and debug the app on-device throughout the build.
Verified environment state (2026-08-19)
| Item | State |
|---|---|
| OS | CachyOS (Arch-based), pacman present |
| JDK | Not installed → Milestone M0 (pacman -S jdk17-openjdk) |
| Android SDK | Not installed → M0 (cmdline-tools + sdkmanager) |
| Gradle | Via project wrapper (gradlew), no system install |
| ADB | Installed; device a5ca2a4b (MIX 2S, API 29) connected |
| Python | 3.14.7; uv 0.12.3 present |
| hermes venv | Not created → M0 (cd hermes-agent && uv sync) |
| hermes core deps | websockets==15.0.1 and httpx are core deps → plugin needs zero new Python deps |
| Disk / RAM | 522 GB free / 62 GB RAM — ample |
Naming
- Product/effort name: Iris × Hermes (folder
iris_x_hermes). - hermes platform name:
iris(the plugin registersPlatform("iris")). - WS default port: 8790 (configurable).
- Default chat id:
default(the home channel).