hermes-mobile-app

Unofficial community project. Not affiliated with or endorsed by Nous Research. Hermes itself is never patched.

Why

Hermes Agent is a powerful agent, but it lives in a terminal. Hermes Mobile gives it a proper phone interface: streaming chat, live tool cards, approvals you can answer from the status bar, a canvas for building things together, and notifications that work while the app is closed. Hermes runs in Termux on the same phone, so the whole thing is self-contained.

Highlights

Answer from the island

Approvals and questions show up on the status chip (an Android 16 Live Update; older versions get a normal notification). One tap on the chip, pick an answer, done. The app does not need to be open.

Renders everything, natively

KaTeX equations, sortable tables with "Copy table", tick-able task lists, Obsidian-style callouts, Mermaid diagrams (full screen, pinch to zoom), coloured diffs, long code that collapses, inline SVG and HTML cards.

A canvas you and Hermes share

Ask for an interactive page or a 3D scene and Hermes builds it live in a document beside the chat. HTML runs in a sandbox that is offline unless you allow it. Every change is a version with a diff you can restore.

Your phone's assistant

Pick Hermes under Default apps → Digital assistant app and long-pressing the power button (or the assist gesture) opens it straight in hands-free Live mode. Settings → Voice shows whether it is on.

Your chats, your memory, your look

Search inside every message, pin, archive, link chats to chats. Every memory write is shown as a diff, and there is a screen to see what Hermes remembers. Dark, OLED black or light.

And more

How it fits together

flowchart LR
  subgraph Phone
    direction LR
    A[Hermes Mobile app<br/>Java shell + React UI] <-->|JSON-RPC over localhost| B[Hermes dashboard<br/>Debian in Termux]
    B --- C[Hermes Agent]
    P[hermes-mobile plugin] -->|status, approvals| S[Foreground service<br/>island chip + notifications]
    C --- P
  end
  C -->|your model provider| M[(LLM API)]

The app talks to the same tui_gateway JSON-RPC connection that Hermes Desktop uses, so it needs no changes to Hermes. A small plugin sends status and approval events to the app's notification service.

Setup

Easiest: one command, or let your AI agent do it

Plug your phone into a computer (Mac, Windows or Linux) and give any coding agent (Claude Code, Codex, Cursor, Gemini CLI…) this prompt:

Read https://raw.githubusercontent.com/omarqaterge/hermes-mobile-app/main/AGENT_INSTALL.md and follow it to set up Hermes on my Android phone.

Or run the setup script yourself, no agent needed. Mac / Linux (Terminal):

curl -fsSL https://raw.githubusercontent.com/omarqaterge/hermes-mobile-app/main/tools/setup-phone.sh -o setup-phone.sh && bash setup-phone.sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/omarqaterge/hermes-mobile-app/main/tools/setup-phone.ps1 | iex

Either way it walks you through turning on USB debugging, then installs Termux, Debian, Hermes Agent, the plugin and the app by itself (20-45 minutes, mostly waiting) and asks you for the model and its API key. You need an Android phone (arm64, Android 8+) with ~6 GB free. The instructions are in AGENT_INSTALL.md if you want to read what it will do.

Honest note: the script was run on a clean Android emulator up to Hermes's own install (which an emulator on a Mac can't finish: its virtual CPU lacks an instruction a library needs), and each later piece was checked on the author's phone. A brand-new phone hasn't done the whole run yet. If something fails, open an issue.

1. Install Termux and Hermes

1. Install Termux from F-Droid (not the Play Store, that version is outdated).

2. Open Termux and paste:

   pkg update -y && pkg install -y proot-distro && proot-distro install debian && proot-distro login debian
   

3. You are now inside Debian. Install Hermes Agent with its own guide, run hermes setup and add your model provider. When Hermes answers you, type exit to get back to Termux.

2. Run the installer

In Termux (not Debian), paste:

curl -fsSL https://raw.githubusercontent.com/omarqaterge/hermes-mobile-app/main/phone/install.sh | bash

It installs the Hermes plugin, lets the app start Hermes, then downloads the app and opens Android's installer: tap Install (allow Termux to install apps if Android asks). Safe to run again, also to update.

3. Open Hermes Mobile

Allow the permissions it asks for (notifications, "run commands in Termux"). It starts Hermes by itself; the first start can take a minute. Say hi.

Recommended: set battery to "Unrestricted" for Hermes Mobile and Termux (on Xiaomi/HyperOS also turn on Autostart), or Android may kill them in the background.

On a computer with Node 20+, JDK 17 and the Android command-line tools (sdkmanager "platforms;android-36" "build-tools;35.0.0"), with the phone plugged in and USB debugging on:

git clone https://github.com/omarqaterge/hermes-mobile-app.git && cd hermes-mobile-app
(cd web && npm ci)
ANDROID_HOME=/path/to/android-sdk JAVA_HOME=/path/to/jdk-17 VERSION_NAME=1.0.0 VERSION_CODE=1 android/build.sh
adb install -r android/build/hermes-mobile.apk

The first build makes a signing key in ~/.android/hermes-mobile.keystore. A self-built app can't be updated with the downloaded one (different key): uninstall it first.

If something goes wrong

First open Settings → Setup check in the app (it also opens by itself when the app can't reach Hermes): it shows what's missing and has a button for each fix.

Optional: install Termux:Boot and put ~/bin/hermes-services in ~/.termux/boot/10-hermes so Hermes starts after a reboot.

How it works

The app talks to the same engine Hermes Desktop uses. Hermes's dashboard, already running on the phone at 127.0.0.1:9119, exposes the tui_gateway JSON-RPC connection at /api/ws. The web interface uses Hermes's own connection client from apps/shared (c