Mocchi — a multi-agent chat client for your Hermes workspace

1Problem & opportunity

1.1 What exists today

Your Hermes install is a fully-featured agent with a fragmented surface area:

• Telegram — one long conversation, no notion of separate agents.
• Dashboard (hermes dashboard) — a web UI, but it embeds the terminal (a PTY running hermes --tui). It's a developer console, not a messaging app.
• CLI / TUI — powerful, zero mobile usability.
• Profiles — you can already run several fully-isolated agents (own home, config, .env, memory, toolsets, cron). They are invisible in every UI.

1.2 The gap

There is no place where you can see "these are my agents, these are the threads, this is what ran overnight." Every capability you have is one CLI flag away, and none of it is legible at a glance or reachable from a phone.

1.3 Two reference projects, two lessons

Verified from the repositories' READMEs and directory listings on 1 Oct 2026. No claim above is inferred from marketing copy alone.

2Product definition

2.1 One-line

A messaging app where every contact is one of your Hermes agents, every channel is a project workspace, and your entire agent fleet is one tap away on your phone.

2.2 Principles

2.3 Personas → features

3Architecture — how we build on Hermes without forking it

This is the load-bearing section. The entire plan rests on one verified finding: Hermes already exposes a complete, typed, documented agent protocol over WebSocket, and the same protocol the Electron desktop app uses. We are a third client of that protocol.

3.1 The two integration seams

Seam A — the JSON-RPC gateway (primary)

ui-tui (Ink)  ──stdio JSON-RPC──┐
apps/desktop (Electron) ──WS────┼──►  tui_gateway/server.py  ──►  AIAgent + tools + sessions
Mocchi (our client)      ──WS────┘
                                ws://<host>/api/ws

• 251 methods in the generated contract (apps/shared/src/gateway-contract.openrpc.json), each with Pydantic Params/Result models declared in tui_gateway/contracts/.
• Server→client requests (the agent asking you something): approval, clarify, sudo, secret, vault.*, connection. This is exactly the approval-card mechanism OpenMausBot hand-builds — we get it from the protocol.
• Replay on reconnect: session.resume + session.events.since + open_requests(sid) re-render still-open questions after a dropped socket. Essential for mobile.
• Session primitives that map 1:1 to chat threads: session.create, session.list, session.resume, session.history, session.branch, session.interrupt, session.steer, session.undo, session.compress, session.usage, session.title.
• Multi-agent: agents.list, session.* carries a profile field, and profiles are bound per activity by a contextvar override.

Seam B — REST (secondary, for non-chat surfaces)

24 routers mounted by hermes_cli/web_server.py, ~200 endpoints, same session token:

Seam C — OpenAI-compatible API (for anything non-Hermes)

gateway/platforms/api_server.py serves /v1/chat/completions, /v1/responses, /v1/models, /api/sessions, /api/runs, /api/jobs behind API_SERVER_KEY — and under gateway.multiplex_profiles, secondary profiles live at /p/<profile>/…. That means a single key + URL prefix can address any agent in the fleet from any SDK.

3.2 Auth and transport

• Gateway WS auth (web_server_chat.py): a browser-minted ticket (single-use, 30 s TTL) passed as ?ticket= or as the hermes-gateway-ticket.<t> WebSocket subprotocol. A device with a long-lived credential is not a browser, so Phase 1 adds a small device-token path (see §7 risk R2).
• REST uses the same ephemeral _SESSION_TOKEN (bearer).
• Transport over Caddy + HTTPS, exactly like bookmarks.marcadrian.com. No new infra.

3.3 Repo layout

openbot/
├── packages/
│   ├── protocol/        # generated OpenAPI/TS types from the Hermes contract (npm script)
│   ├── client/          # transport-agnostic agent client (WS + reconnect + replay + tickets)
│   └── ui/              # shared design system: roster, thread, approval card, channel
├── apps/
│   ├── web/             # React + Vite PWA  (served at mocchi.yourdomain)
│   └── ios/             # SwiftUI, shares the OpenAPI contract
└── plugins/
    └── mocchi-bridge/   # out-of-tree Hermes plugin: device tokens + optional push

Monorepo, pnpm. One protocol package, two clients — the web app and the iOS app can never disagree about the wire.

4Feature specification

4.1 F1 — Roster (the core screen)

Every profile is an "agent". Data from /api/profiles + agents.list + session.most_recent.

acceptance Cold start shows the fleet in <1 s from a warm cache, with a skeleton while /api/profiles resolves. Pull-to-refresh. New-agent FAB deep-links to profile creation on the desktop dashboard for v1 (creating a profile from mobile is P2).

4.2 F2 — Thread (chat)

Styled messages (not a raw terminal): markdown, code fences, collapsible tool-call cards, streaming token rendering, and a live activity strip (tool name, elapsed, running/done/failed).

• Send via session.steer / the composer method; interrupt via session.interrupt.
• Composer supports slash commands with live completion via complete.slash and complete.path — i.e. /skills, /model, /cron all work from the phone.
• Attachments via /api/chat/image-upload and /api/files/upload.

acceptance Reconnect mid-turn: on socket drop and reconnect, session.resume + session.events.since restores the full transcript and any in-flight turn, with no duplicated or lost text.

4.3 F3 — Approval cards highest leverage

The single most valuable feature, and the cheapest: the protocol already pushes approval / sudo / secret / clarify / vault.* requests to the client and blocks the agent thread until answered.

• Render as an inline card: what it wants, why, risk tier, Allow / Deny / Always-allow-for-10-min.
• Push notification with the question in the body — this is what makes the phone worth having.
• Must declare client.capabilities {server_requests: true} on connect or the server fails fast.

acceptance A tool asks for approval while the app is backgrounded → push arrives → tapping it opens the thread → one tap answers → the agent unblocks.

4.4 F4 — Channels

A channel = profile + working folder + shared instructions + a thread set. Backed by Hermes chat workspaces (/api/chat/workspaces) and session.workspace.move. v1 ships Work / Personal / one channel per real project; the roster inside a channel is a set of profiles.

4.5 F5 — Fleet inspector

Per agent: model, active toolsets (/api/tools/toolsets), skills on/off, memory provider, cron jobs (/api/cron/jobs), token spend (session.usage, /api/analytics/usage), and a "run this agent now" button. Read-mostly in v1; mutations are limited to model switch and skill toggle, both of which are already safe endpoints.

4.6 F6 — Automations

Cron as a first-class screen: list, pause/resume, trigger now (/api/cron/fire), delivery targets (/api/cron/delivery-targets), and blueprint instantiation. Combined with F3, this is the "it worked while I slept" loop.

4.7 F7 — Files from the phone

/api/fs/list + /api/fs/read-text + /api/files/upload + /api/git/status. Read a diff on the train, push a fix. Deliberately scoped: review, not a full IDE.

4.8 F8 — Voice (P2)

/api/audio/transcribe for input and /api/audio/speak / speak-stream for playback of replies. /api/audio/voice-live/session may support a live mode later.

4.9 Non-goals for v1

• ❌ Re-implementing the agent, tool runner, memory or skill system.
• ❌ Composio-style app marketplace (Hermes already has MCP + providers + 20 channels).
• ❌ A cloud desktop / VM per agent (OpenMausBot's most expensive subsystem, least relevant to you).
• ❌ Writing to Hermes core. Every addition is a plugin or a client.

5Platform specifics

5.1 Web (PWA)

React 19 + Vite, installable, offline shell. Design language: dark-glass panels, subtle borders, pill-shaped bottom dock — matching the Mocchi bookmarks app you already have, so the fleet feels like the same product family.

5.2 iOS

5.3 Auth & pairing (the honest hard part)

Browser WS auth uses a 30-second single-use ticket minted in-page. A native app has no browser page, so it needs a long-lived credential. Rather than touching Hermes core, add an out-of-tree plugin (~/.hermes/plugins/mocchi-bridge) exposing a narrow device-token endpoint — this is rung 4 on Hermes' own Footprint Ladder, and the plugin API is the documented, stable extension point.

Flow: desktop dashboard shows a QR with a short code → phone submits it once → device token stored in the iOS Keychain → all subsequent calls bearer-auth. Revoke via /api/pairing/revoke.

5.4 Push

APNs token registered by the device; a Hermes plugin subscribes to agent events and dispatches. Push is only sent for genuinely interrupt-worthy events: approval requests, completed long runs, and cron results — never for ordinary chatter, or you'll mute the app within a week.

6Implementation plan

6.1 Total effort & sequencing

Strongly recommended: stop after Phase 1 and use it for two weeks before committing to iOS. Phase 1 delivers ~80% of the value at ~35% of the cost, and the feedback will make Phases 2–3 much sharper. Committing to native before the web client has proven the IA is the classic mistake.

7Risks & mitigations

8Success criteria

• Adoption: 80%+ of your Hermes interactions happen through Mocchi within 30 days.
• Latency: first token on screen < 400 ms p50 on a warm connection.
• Resilience: zero message loss across 100 forced socket drops mid-turn.
• Approval latency: phone-only approval of a risky action completes in < 10 s.
• Update resilience: a hermes update followed by the Phase-0 test is the only work required to re-validate the client.
• Zero divergence: no fork, no patch file against hermes-agent.

9Open questions

1. Profile-per-role or session-per-role? Profiles are true agents with isolated memory, but they are heavy to create from a phone. Recommend: profiles for genuine roles (research, KDP, ops), sessions for variations within one.
2. Should the phone get its own restricted profile? Recommendation: yes, as a safety valve — an "operator" profile with a reduced toolset, sharing your memory read-only.
3. iOS or Android first? iOS assumed. OpenMausBot ships both; you use Telegram on iOS.
4. Do we want team/agent-relay surfaces (Phase 4)? Upstream bot_relay.roster/deliver already support agent-to-agent messaging; surfacing it is cheap but adds product surface — defer until the core is used daily.
5. Public or private? Recommendation: private, MIT or Apache-2.0, single-user. Multi-tenant auth is a different and much larger product.

Sources. Hermes integration surfaces verified by direct inspection of the installed source at /home/ubuntu/.hermes/hermes-agent (v0.21.3, commit 4d14aaf) on 1 Oct 2026: tui_gateway/contracts/, apps/shared/src/gateway-contract.openrpc.json, hermes_cli/web_routers/, hermes_cli/web_server*.py, gateway/platforms/api_server.py, tui_gateway/AGENTS.md. Reference projects read from their public repositories on 1 Oct 2026. No unverified claim in this document is presented as fact.