# Hermes Mobile

Android-first native client for a remote [Hermes Agent](https://github.com/NousResearch/hermes-agent) gateway/API server, with a legacy local companion retained for compatibility.

The current beta path is a Kotlin/Jetpack Compose thin client that connects directly to an upstream Hermes gateway. Hermes remains authoritative for authentication, sessions, streaming, tools, and backend behavior.

## Current Android Beta

- Native Kotlin/Compose chat, session, settings, adaptive layout, and accessibility foundations.
- Direct HTTPS gateway configuration with bearer/no-auth support and local-first routing.
- Capability-gated session streaming and tool lifecycle output.
- Semantic Android beta metadata at `v0.1.0-beta.1`.

Build and clean-install instructions are in [Android Beta Build and Install](docs/ANDROID_BETA_BUILD.md). Device installation and the release criteria remain unverified until recorded on a real device or emulator.

## Monorepo

```text
apps/mobile       Vite React + Capacitor Android app
apps/companion    Fastify local companion server
packages/shared   Shared TypeScript API schemas/types
docs              Product, architecture, install, and API notes
```

## Install Dependencies

This repo works with npm workspaces:

```bash
npm install
```

## Companion Setup and Run

Generate/persist a local access key:

```bash
npm run companion:setup
```

The command prints:

- Config path, normally `~/.config/hermes-mobile/companion.json`
- Safe workspace root
- Access key such as `hm_...`

Start the companion server:

```bash
npm run companion:dev
```

The server listens on `0.0.0.0:8787` by default. Useful overrides:

```bash
PORT=8787 HOST=0.0.0.0 HERMES_MOBILE_WORKSPACE_ROOT=/path/to/workspace npm run companion:dev
```

All non-health endpoints require `Authorization: Bearer <access-key>`.

## Mobile Development

Run the browser/PWA development shell:

```bash
npm run mobile:dev
```

Open Settings in the app and use:

- Android emulator URL: `http://10.0.2.2:8787`
- Physical device URL: `http://<your-computer-lan-ip>:8787`
- Access key: value printed by `npm run companion:setup`

Tap **Test connection** to validate the server and key.

## Android APK Build

Build the native direct-gateway client without Capacitor synchronization:

```bash
npm run android:build:debug
```

See [Android Beta Build and Install](docs/ANDROID_BETA_BUILD.md) for prerequisites, the versioned APK path, package checks, clean installation, direct-gateway setup, and known limitations.

## Companion API

- `GET /api/health` — no token required; returns service, Hermes CLI, workspace, and uptime.
- `GET /api/auth/validate` — validates `Authorization: Bearer <key>`.
- `POST /api/chat` — sends `{ "prompt": "..." }` to local `hermes` CLI when available.
- `GET /api/files?path=.` — lists workspace files/directories.
- `GET /api/files/read?path=README.md` — reads UTF-8 file content.
- `POST /api/files/write` — writes `{ "path": "notes.txt", "content": "..." }`.
- `GET /api/files/metadata?path=README.md` — returns download-style file metadata.
- `POST /api/terminal/run` — runs `{ "command": "pwd && ls", "cwd": ".", "timeoutMs": 10000 }` under the workspace root.

## Docs

- [Companion Server](docs/COMPANION_SERVER.md)
- [Mobile App Structure](docs/MOBILE_APP.md)
- [Architecture](docs/ARCHITECTURE.md)
- [Product Plan](docs/PRODUCT_PLAN.md)
- [Install Strategy](docs/INSTALL.md)
- [Testing Strategy](docs/TESTING.md)
- [Roadmap](docs/ROADMAP.md)