Iris × Hermes

A native Android + Desktop experience for hermes-agent, connected through a gateway platform plugin.

⚠️ 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.

Start here

📚 The full implementation reference library is in docs/. Read docs/00-overview.md first, then follow the numbered docs.

Quickstart

Full walkthrough: docs/setup.md.

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.

Pairing notes

• 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.

The three deliverables (this monorepo)

Path	What
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).

The Android and Desktop clients live in one Compose Multiplatform Gradle project (app/) with a shared KMP module (app/shared).

Status

• Phase: M0–M6 complete; M7 (polish + E2E + docs) in progress.
• Milestones: see docs/14-milestones.md.
• Locked decisions: see docs/16-open-questions.md.

Quick orientation

• Architecture + rationale → docs/01-architecture.md
• Wire protocol → docs/04-wire-protocol.md (+ docs/protocol/frames.schema.json)
• Gateway plugin design → docs/03-gateway-plugin.md
• hermes source cheat-sheet → docs/15-hermes-reference.md
• Toolchain setup → docs/12-toolchain.md