# Iris × Hermes

A **native Android + Desktop** experience for [hermes-agent](https://github.com/NousResearch/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/`](docs/README.md).**
Read `docs/00-overview.md` first, then follow the numbered docs.

## Quickstart

Full walkthrough: [`docs/setup.md`](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`](docs/14-milestones.md).
- **Locked decisions:** see [`docs/16-open-questions.md`](docs/16-open-questions.md).

## Quick orientation

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