ARIA/iris_x_hermes
1
0 Fork 0
Code Issues 2 Pull Requests Actions Packages Projects 1 Releases 4 Wiki Activity

README: rewrite for users — what it is, feature list, build-from-source (gateway/Android/desktop/pairing), contributing, Apache-2.0 license; add LICENSE file

Browse Source
This commit is contained in:
ARIA committed 2026-08-21 01:17:23 +02:00
1 parent 73815b032a
commit f79c54fead
2 files changed
+322 -40
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.md
+121 -40
View File
@@ -1,57 +1,138 @@
# Iris × Hermes
A **native Android + Desktop** experience for [hermes-agent](https://github.com/NousResearch/hermes-agent), connected through a **gateway platform plugin**.
A chat app for [hermes-agent](https://github.com/NousResearch/hermes-agent): a **native Android app** and a **desktop app** (Linux, macOS, Windows) — both built from one shared Kotlin codebase (Compose Multiplatform).
> ## ⚠️ HARD RULES
> 1. **`hermes-agent/` is a read-only research reference. It is git-ignored and
> must NEVER be committed, pushed, or shipped.** We only *install* our plugin
> into a live hermes home (`~/.hermes/plugins/android`); we never modify hermes
> core.
> 2. **ADB is installed and a device is connected** (`a5ca2a4b`, Xiaomi MIX 2S,
> Android 10 / API 29). Use it to install/launch/debug the app on-device.
Iris pairs with your running `hermes gateway` over a private WebSocket and gives you a Telegram-quality chat experience with your personal agent: streaming replies, visible reasoning, structured tool activity, channels, threads, media, search, and push notifications.
## Start here
## Features
📚 **The full implementation reference library is in [`docs/`](docs/README.md).**
Read `docs/00-overview.md` first, then follow the numbered docs.
- **Native Hermes-Gateway integration** — your hermes → gateway → Iris app
- **Absolute Privacy!** — everything stays on your own infrastructure
- **No file limit**
- **No character limit**
- **Full markdown support** — tables, checkmarks, bold, inline code, code blocks + syntax highlighting…
- **HTML Artifact Preview** — agent-sent HTML/CSS/JS rendered in an in-app WebView
- **All settings live in the app**, not in hermes `config.yml`! Change everything on the fly.
- **Channels** — create channels to keep track of your reports, cronjobs, webhook calls
- **Pin channels, rename them, change the color/icon**
- **Customize how your chat should look like** — color? Check! Images? Check!
- **Reasoning collapse/expandable** in the chat bubble
- **Change the default behavior** of tool & reasoning verbosity
- **Threads** — create your own, or let the AI create them with a title
- **Search messages from everywhere**
## Quickstart
## How it works
Full walkthrough: [`docs/setup.md`](docs/setup.md).
```
hermes-agent ──> hermes gateway ──(WebSocket :8790)──> Iris app (Android / Desktop)
```
1. **Gateway:** install the plugin (`ln -s "$PWD/gateway-plugin" ~/.hermes/plugins/android`), run `hermes gateway setup` (generates the pairing token, prints the server URL), then `hermes gateway`.
2. **App:** `cd app && ./gradlew :androidApp:installDebug` (Android; ADB device connected) or `./gradlew :desktopApp:run` (desktop).
3. **Pair:** on the app's Connect screen, enter the server URL (`ws://<gateway-ip>:8790/ws`) + pairing token, then **Test & Connect**.
4. **Chat.**
- `gateway-plugin/` is a hermes **platform plugin** (`android`). It runs inside the
`hermes gateway` process and opens a WebSocket server the apps connect to.
Zero new Python dependencies, zero hermes-core changes.
- `app/` is one Compose Multiplatform Gradle project: `:shared` (KMP, most of the
code), `:androidApp` (native Kotlin + Jetpack Compose client), `:desktopApp`
(the same app, tweaked for a big screen).
- The app is a first-class hermes *messaging platform*, so everything the gateway
already does just works: slash commands, cron delivery, `send_message` routing,
coexistence with Telegram/Discord/etc.
- Push notifications: FCM (primary) or ntfy (fallback).
### Pairing notes
## Build from source
- **Token location:** `~/.hermes/.env` on the gateway host (`ANDROID_TOKEN`), or the `hermes gateway setup` output (printed once, at generation).
- **Manual entry only:** the app has no QR scanner yet — the server prints a QR payload, but you type the URL + token.
- **Default bind is `127.0.0.1`:** for a phone on the LAN, set `ANDROID_WS_HOST` to the gateway's LAN IP.
### Prerequisites
## The three deliverables (this monorepo)
| Path | What |
| Where | You need |
|---|---|
| `gateway-plugin/` | Python hermes **platform plugin** (`android`). Runs in the `hermes gateway` process; opens a WebSocket server the apps connect to. Zero new Python deps, zero hermes-core changes. |
| `app/androidApp` | Native **Kotlin + Jetpack Compose** client. |
| `app/desktopApp` | **Kotlin + Compose Multiplatform** client — the Android app, tweaked for a big screen (shares `app/shared`). |
| Gateway host | [hermes-agent](https://github.com/NousResearch/hermes-agent) with its venv (`uv sync`) |
| Android build machine | JDK 17, Android SDK (`sdk.dir` in `app/local.properties` or `ANDROID_HOME`), ADB with a connected device |
| Desktop build machine | JDK 17 only |
The Android and Desktop clients live in **one Compose Multiplatform Gradle
project** (`app/`) with a shared KMP module (`app/shared`).
No system Gradle needed — both apps use the project wrapper (`./gradlew`).
## Status
### 1. Gateway (on the gateway host)
- **Phase:** M0–M6 complete; M7 (polish + E2E + docs) in progress.
- **Milestones:** see [`docs/14-milestones.md`](docs/14-milestones.md).
- **Locked decisions:** see [`docs/16-open-questions.md`](docs/16-open-questions.md).
```bash
# hermes-agent is a separate project (not part of this repo)
cd hermes-agent && uv sync
## Quick orientation
# install the Iris plugin into the live hermes home
mkdir -p ~/.hermes/plugins
ln -s "$PWD/gateway-plugin" ~/.hermes/plugins/android
hermes gateway status # should list "android"
- Architecture + rationale → [`docs/01-architecture.md`](docs/01-architecture.md)
- Wire protocol → [`docs/04-wire-protocol.md`](docs/04-wire-protocol.md) (+ [`docs/protocol/frames.schema.json`](docs/protocol/frames.schema.json))
- Gateway plugin design → [`docs/03-gateway-plugin.md`](docs/03-gateway-plugin.md)
- hermes source cheat-sheet → [`docs/15-hermes-reference.md`](docs/15-hermes-reference.md)
- Toolchain setup → [`docs/12-toolchain.md`](docs/12-toolchain.md)
</file>
hermes gateway setup # generates ANDROID_TOKEN, prints the server URL
hermes gateway # run the gateway
```
### 2. Android app
```bash
cd app
./gradlew :androidApp:installDebug # build + install on the connected ADB device
# or just build the APK:
./gradlew :androidApp:assembleDebug # → app/androidApp/build/outputs/apk/debug/
```
### 3. Desktop app
```bash
cd app
./gradlew :desktopApp:run # dev run
./gradlew :desktopApp:jpackage # native app-image (bundles the JRE)
```
### 4. Pair
On the app's **Connect** screen:
1. **Server URL** — `ws://<gateway-ip>:8790/ws` (printed by `hermes gateway setup`).
2. **Pairing token** — from the setup output, or `ANDROID_TOKEN` in `~/.hermes/.env`
on the gateway host.
3. **Test & Connect.**
Notes:
- The app has **no QR scanner** — pairing is manual URL + token entry.
- The default bind is `127.0.0.1` (desktop on the same machine only). For a phone
on the LAN, set `ANDROID_WS_HOST` to the gateway's LAN IP.
- Remote access: Tailscale/WireGuard, or a reverse proxy with CA-signed WSS
(`ANDROID_WS_CERT` / `ANDROID_WS_KEY`).
Full walkthrough, push setup (FCM/ntfy), and troubleshooting:
[`docs/setup.md`](docs/setup.md).
## Contributing
Contributions are welcome! Before you start:
1. **Read the docs.** The full reference library is in [`docs/`](docs/README.md) —
start with [`docs/00-overview.md`](docs/00-overview.md), then follow the
numbered docs (architecture, wire protocol, plugin design, testing, …).
2. **Know the layout.**
| Path | What |
|---|---|
| `gateway-plugin/` | Python hermes platform plugin (`android`); `protocol.py` is the frame source of truth |
| `app/shared` | KMP module with most of the client code (shared by Android + Desktop) |
| `app/androidApp` | Thin Android shell (package `dev.iris.app`) |
| `app/desktopApp` | Thin desktop shell |
| `docs/` | Numbered reference library |
3. **Run the tests.**
- Python (gateway plugin): `cd hermes-agent && scripts/run_tests.sh tests/gateway/test_android.py`
(never bare `pytest` — hermes's runner sandboxes `HERMES_HOME`).
- Kotlin: `cd app && ./gradlew :shared:testDebugUnitTest`
- Live check (gateway must be running): `gateway-plugin/tests/ws_probe.py` and
`gateway-plugin/tests/e2e.py` — see [`gateway-plugin/tests/README.md`](gateway-plugin/tests/README.md).
4. **Keep the protocol in sync.** `gateway-plugin/protocol.py`,
`app/shared/.../protocol/Protocol.kt`, and `docs/protocol/frames.schema.json`
must always agree.
5. **Pre-commit hooks** are configured (`.pre-commit-config.yaml`); run
`pre-commit install` once after cloning.
Open an issue first for anything big, then send a pull request.
## License
Apache License 2.0 — see [LICENSE](LICENSE).