From 7c4735ed1ce4866ef6b3fbcd88b64a1773ef401d Mon Sep 17 00:00:00 2001 From: M57 <41645758+Hy4ri@users.noreply.github.com> Date: Thu, 18 Jun 2026 19:09:46 +0300 Subject: [PATCH] docs(#15): add comprehensive README (#16) Co-authored-by: M57 --- README.md | 305 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 305 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 00000000..b597b6a1 --- /dev/null +++ b/README.md @@ -0,0 +1,305 @@ +
+
+ Android + Jetpack Compose + Kotlin + Material You +

+
+ +

Hermes Control

+

Remote control for your Hermes AI agent — from your pocket.

+ +

+ Features • + Screenshots • + Quick Start • + Project Structure • + Tech Stack • + Contributing • + Releases +

+ +

+ Latest Release + CI + Last Commit + minSdk 26 + targetSdk 36 +

+ +--- + +## Overview + +**Hermes Control** is a native Android companion app for [Hermes Agent](https://hermes-agent.nousresearch.com) — the open-source, multi-platform AI assistant by Nous Research. + +Instead of pulling out a laptop or switching to Telegram/Discord, you can manage your Hermes agent directly from your phone: + +- 💬 Chat with your agent in real time +- 🔧 Inspect and reconfigure system settings, profiles, and plugins +- 📊 Monitor gateway status, MCP servers, and webhook health +- 📋 Manage cron jobs, environment keys, and toolsets +- 🗂️ Track kanban boards and agent achievements +- 🔄 Pull-to-refresh every data screen + +All this with a **Material You** design that adapts to your device's dynamic color theme. + +--- + +## Features + +### 🤖 Agent Chat +- Real-time message exchange with your Hermes agent +- Session management with profile switching +- Message history with persistent storage (Room) + +### ⚙️ System Management +- **Profiles** — View and switch between Hermes agent profiles +- **Skills** — Browse installed skills with inline descriptions +- **Plugins** — Manage active plugins and their configurations +- **Toolsets** — See which toolsets are enabled per profile + +### 🛠️ Operations +- **Cron Jobs** — View scheduled tasks, their schedules, and last-run status +- **Webhooks** — Configure and test webhook endpoints +- **Keys & Credentials** — Securely manage environment variables +- **Logs** — Stream and filter agent logs + +### 📡 Connectivity +- **Gateway Status** — Monitor WebSocket and API gateway health +- **MCP Servers** — Manage Model Context Protocol server connections +- **Channels** — View connected messaging platform status + +### 📊 Productivity +- **Kanban Boards** — Track tasks across boards, columns, and cards +- **System Info** — Runtime environment and configuration overview +- **Achievements** — Agent milestone tracker + +### 🎨 UX +- **Material You** — Dynamic color theming from your wallpaper +- **Pull-to-Refresh** — Swipe down on any data screen to reload +- **Shared Scaffold** — Consistent navigation and layout across all screens +- **Scroll-aware TopBar** — Collapsing top bar on scroll + +--- + +## Screenshots + +> 📸 Screenshots coming soon. Build the app and see it in action! + +| Chat | System | Profile | Kanban | +|:---:|:---:|:---:|:---:| +| 🔲 | 🔲 | 🔲 | 🔲 | + +--- + +## Quick Start + +### Prerequisites + +| Tool | Version | Reason | +|------|---------|--------| +| [JDK](https://adoptium.net/) | 17+ | Kotlin/JVM compilation | +| [Android Studio](https://developer.android.com/studio) | Hedgehog+ | IDE + SDK management | +| Android SDK | 36 (compile), 26 (min) | Via Android Studio SDK Manager | +| Git | any | Clone the repo | + +### Clone & Build + +```bash +git clone https://github.com/Hy4ri/hermes-mobile.git +cd hermes-mobile +./gradlew assembleDebug +``` + +The debug APK will be at `app/build/outputs/apk/debug/app-debug.apk`. + +### Build with custom version + +```bash +./gradlew assembleRelease -PversionName="1.2.0" -PversionCode="120" +``` + +> **Note:** Release builds use debug signing keys by default. For Play Store distribution, configure a proper signing config. + +### Install + +```bash +adb install app/build/outputs/apk/debug/app-debug.apk +``` + +Or open the project in Android Studio and hit **Run ▶**. + +--- + +## Project Structure + +``` +hermes-mobile/ +├── app/ +│ ├── src/ +│ │ ├── main/ +│ │ │ ├── java/com/m57/hermescontrol/ +│ │ │ │ ├── Navigation.kt # NavHost + screen routing +│ │ │ │ ├── NavigationController.kt # Drawer + bottom nav controller +│ │ │ │ ├── NavigationKeys.kt # Route constants +│ │ │ │ ├── MainActivity.kt # Single activity entry point +│ │ │ │ ├── HermesControlApp.kt # App-level composable root +│ │ │ │ ├── data/ +│ │ │ │ │ ├── model/ # API models (DTOs) +│ │ │ │ │ ├── remote/ # Retrofit API client +│ │ │ │ │ └── local/ # Room database +│ │ │ │ ├── theme/ +│ │ │ │ │ ├── Theme.kt # Material You dynamic theming +│ │ │ │ │ ├── Color.kt # Color palette definitions +│ │ │ │ │ ├── Type.kt # Typography scale +│ │ │ │ │ └── Motion.kt # Shared transition animations +│ │ │ │ └── ui/ +│ │ │ │ ├── common/ # Shared components +│ │ │ │ │ ├── HermesScaffold.kt # Standardized screen layout +│ │ │ │ │ ├── EmptyState.kt # Empty list placeholder +│ │ │ │ │ └── LoadingState.kt # Loading spinner component +│ │ │ │ ├── chat/ # Chat screen +│ │ │ │ ├── config/ # Raw config viewer +│ │ │ │ ├── profiles/ # Profile management +│ │ │ │ ├── skills/ # Skills browser +│ │ │ │ ├── plugins/ # Plugin management +│ │ │ │ ├── toolsets/ # Toolset viewer +│ │ │ │ ├── cron/ # Cron job viewer +│ │ │ │ ├── webhooks/ # Webhook management +│ │ │ │ ├── logs/ # Log stream viewer +│ │ │ │ ├── keys/ # Environment variable manager +│ │ │ │ ├── gateway/ # Gateway health monitor +│ │ │ │ ├── mcp/ # MCP server manager +│ │ │ │ ├── channels/ # Messaging channels +│ │ │ │ ├── pairing/ # Device pairing +│ │ │ │ ├── kanban/ # Kanban board viewer +│ │ │ │ ├── model/ # LLM model selector +│ │ │ │ ├── system/ # System info screen +│ │ │ │ └── achievements/ # Agent achievements +│ │ │ ├── res/ +│ │ │ │ ├── values/ +│ │ │ │ │ └── strings.xml # String resources +│ │ │ │ ├── drawable/ # Vector icons & drawables +│ │ │ │ └── mipmap-*/ # Launcher icons +│ │ │ └── AndroidManifest.xml +│ │ └── test/ # Unit tests +│ │ └── kotlin/com/m57/hermescontrol/ +│ └── build.gradle.kts # App-level build config +├── gradle/ +│ └── libs.versions.toml # Version catalog +├── .github/ +│ └── workflows/ +│ ├── android.yml # CI (ktlint + unit tests) +│ └── release.yml # Release APK builder +├── build.gradle.kts # Root build config +├── settings.gradle.kts # Project settings +└── gradlew # Gradle wrapper +``` + +--- + +## Tech Stack + +| Category | Library | Purpose | +|----------|---------|---------| +| **Language** | [Kotlin 2.3+](https://kotlinlang.org/) | Primary language | +| **UI** | [Jetpack Compose](https://developer.android.com/develop/ui/compose) (BOM 2026.03.01) | Declarative UI | +| **Design** | [Material3](https://m3.material.io/) (Compose) + Material You | Dynamic theming | +| **Navigation** | [Navigation3](https://developer.android.com/develop/ui/compose/navigation) | Screen routing | +| **Networking** | [Retrofit 2](https://square.github.io/retrofit/) + [OkHttp 4](https://square.github.io/okhttp/) | REST API calls | +| **Persistence** | [Room](https://developer.android.com/training/data-storage/room) (SQLite) | Local message history | +| **Encryption** | AndroidX Security Crypto | Secure key storage | +| **Background** | [WorkManager](https://developer.android.com/topic/libraries/architecture/workmanager) | Notification polling | +| **Serialization** | [Gson](https://github.com/google/gson) | JSON parsing | +| **Testing** | jUnit 5 + [MockK](https://mockk.io/) + [OkHttp MockWebServer](https://github.com/square/okhttp/tree/master/mockwebserver) | Unit testing | +| **Linting** | [ktlint](https://ktlint.github.io/) | Kotlin code style | + +--- + +## Architecture + +The app follows a **single-activity, Compose-first** architecture with MVVM: + +``` +View (Composable) → ViewModel → ApiClient (Retrofit) → Hermes Agent (HTTP) +``` + +- **Screens** are pure Compose functions that observe `StateFlow` from their ViewModel +- **ViewModels** manage UI state and call the API client +- **ApiClient** is a Retrofit-based HTTP client that talks to the Hermes Agent REST API +- **Navigation** uses a custom NavHost with drawer-based routing + +--- + +## Contributing + +PRs are welcome! Here's the workflow: + +1. **Pick an issue** — or create one first to discuss the change +2. **Branch** from `main` — use `feat/issue-N-description` or `fix/issue-N-description` +3. **Implement** — one PR per logical change +4. **CI must pass** — ktlint + lintDebug + unit tests run on every PR +5. **Squash merge** into `main` + +### Code style + +- ktlint enforces consistent formatting (`./gradlew ktlintCheck`) +- Use `HermesScaffold` for new screens (never raw Material3 `Scaffold`) +- Compose parameters follow the standard order: `modifier`, callbacks, content + +### PR checklist + +- [ ] Branch from `main` and target `main` +- [ ] CI is green (ktlint, lint, tests) +- [ ] No unused imports or dead code +- [ ] `contentDescription` on all `Image`/`Icon` elements (accessibility) +- [ ] Follows the existing pattern for similar screens + +--- + +## Releases + +Pre-built APKs are available on the [Releases page](https://github.com/Hy4ri/hermes-mobile/releases). + +Each release is built automatically by CI when a maintainer pushes a `v*` tag: + +```bash +git tag v1.2.0 +git push origin v1.2.0 +``` + +The `release.yml` workflow will: +1. Run full CI (ktlint, lint, tests) +2. Build a release APK with the correct version +3. Create a GitHub Release with auto-generated notes +4. Attach the APK as a downloadable asset + +--- + +## License + +``` +Copyright 2026 Hy4ri + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +``` + +--- + +

+ Built with ❤️ by Hy4ri +
+ Hermes Agent by Nous Research +