Hermes Control

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

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

---

Overview

Hermes Control is a native Android companion app for Hermes Agent — 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	17+	Kotlin/JVM compilation
Android Studio	Hedgehog+	IDE + SDK management
Android SDK	36 (compile), 26 (min)	Via Android Studio SDK Manager
Git	any	Clone the repo

Clone & Build

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

./gradlew assembleRelease -PversionName="1.2.0" -PversionCode="120"

Note: Release builds require proper signing configuration. Ensure the environment variables KEYSTORE_PATH, KEYSTORE_PASSWORD, KEY_ALIAS, and KEY_PASSWORD are set before building.

Install

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              # Drawer + NavDisplay + entry wiring
│   │   │   │   ├── NavigationController.kt    # Central navigation guard (dedup)
│   │   │   │   ├── NavigationKeys.kt          # Screen key definitions
│   │   │   │   ├── MainActivity.kt            # Single activity entry point
│   │   │   │   ├── data/
│   │   │   │   │   ├── model/                 # API models / DTOs (20+ files)
│   │   │   │   │   ├── remote/                # Retrofit + OkHttp API client
│   │   │   │   │   ├── local/                 # Room DB (Dao, Entity, Mapper)
│   │   │   │   │   └── ws/                    # WebSocket TUI Gateway (JSON-RPC 2.0)
│   │   │   │   ├── notification/
│   │   │   │   │   └── ChatNotificationService.kt  # Foreground service for reply alerts
│   │   │   │   ├── theme/
│   │   │   │   │   ├── Theme.kt               # Material You dynamic theming
│   │   │   │   │   ├── Color.kt               # Color palette definitions
│   │   │   │   │   ├── HermesStatusColors.kt  # Semantic status colours (CompositionLocal)
│   │   │   │   │   ├── Type.kt                # Typography scale
│   │   │   │   │   ├── Motion.kt              # Shared transition animations
│   │   │   │   │   ├── Spacing.kt             # Spacing tokens (CompositionLocal)
│   │   │   │   │   └── Shapes.kt              # Shape tokens
│   │   │   │   ├── ui/
│   │   │   │   │   ├── common/                # Shared components
│   │   │   │   │   │   ├── HermesScaffold.kt  # Standardised screen layout
│   │   │   │   │   │   ├── StateViews.kt      # Loading, error, empty placeholders
│   │   │   │   │   │   └── SharedComponents.kt # SearchBar, FilterChips, ToggleRow, etc.
│   │   │   │   │   ├── chat/                  # Chat screen + view model
│   │   │   │   │   ├── settings/              # Settings screen + view model
│   │   │   │   │   ├── connect/               # Connect / pairing screen
│   │   │   │   │   ├── 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
│   │   │   │   │   ├── model/                 # LLM model selector
│   │   │   │   │   ├── channels/              # Messaging channels
│   │   │   │   │   ├── pairing/               # Device pairing
│   │   │   │   │   ├── config/                # Raw config viewer
│   │   │   │   │   ├── system/                # System info screen
│   │   │   │   │   ├── kanban/                # Kanban board viewer
│   │   │   │   │   └── achievements/          # Agent achievements
│   │   │   │   └── util/                      # Utility classes
│   │   │   │       └── CronExpressionFormatter.kt
│   │   │   ├── 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

\n---

Tech Stack

Category	Library	Purpose
Language	Kotlin 2.3+	Primary language
UI	Jetpack Compose (BOM 2026.03.01)	Declarative UI
Design	Material3 (Compose) + Material You	Dynamic theming
Navigation	Navigation3	Screen routing
Networking	Retrofit 2 + OkHttp 4	REST API calls
Persistence	Room (SQLite)	Local message history
Encryption	AndroidX Security Crypto	Secure key storage
Background	Foreground Service	Notification polling (ChatNotificationService)
Serialization	Gson	JSON parsing
Testing	jUnit 5 + MockK + OkHttp MockWebServer	Unit testing
Linting	ktlint	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.

Each release is built automatically by CI when a maintainer pushes a v* tag:

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.