Herald OS - Moses Yebei

The Problem

Managing a machine through menus and file trees can be slow and error‑prone. Users who rely on an AI assistant need a unified interface that can open apps, search files, and perform system‑level tasks without leaving the chat window.

What This Does

Herald OS is a lightweight operating‑system shell that runs on top of Hermes Agent. It exposes a set of Electron‑based desktop commands and a set of backend services that translate agent intents into OS actions.

apps/desktop/electron/main.ts boots the Electron process.
apps/desktop/electron/platform/index.ts wires platform‑specific helpers (e.g., macOS accessibility, Linux shell).
IPC modules such as apps/desktop/electron/ipc/apps.ts and .../ipc/system.ts receive commands from the Hermes bridge and dispatch them to backend services (apps/desktop/electron/backend/*).
Backend modules (catalog.ts, probe.ts, shell-env.ts, context.ts) perform the actual file‑system, process, and environment queries.
The hermes-client package in packages/hermes‑client provides the bridge that registers Herald OS as a plugin for Hermes.

How It Is Wired

Entry Point – apps/desktop/electron/main.ts

import { app } from "electron";
import { startPlatform } from "./platform";
app.whenReady().then(() => startPlatform());

Platform Wiring – platform/index.ts loads the bridge plugin, creates the preload script, and exposes the IPC handlers.

import { registerBridge } from "./bridge-plugin";
registerBridge();

IPC Flow – e.g., a user asks Hermes to list files.

Hermes sends a message to ipc/catalog.ts.
ipc/catalog.ts calls backend/catalog.ts::listFiles.
backend/catalog.ts uses Node’s fs API to read the directory and returns the list.
The result is sent back to Hermes via the bridge.

External Touchpoints –

Filesystem (fs module) for catalog and context snapshots.
Process list (process module) via probe.ts.
Shell commands (child_process) in shell-env.ts.
Screen recording/access APIs on macOS when the user interacts with the screen.

Responsibility Blocks

main.ts – Electron bootstrap.
platform/index.ts – OS‑specific feature registration.
ipc/* – Command dispatch.
backend/* – System‑level operations.
bridge-plugin.ts – Hermes plugin registration.

The module graph shows a single cycle between bridge-plugin.ts and ipc/*, a common pattern in Electron apps. Changing the bridge logic requires touching only these files.

How To Use It

Setup

git clone https://github.com/moses-y/Herald-OS
cd Herald-OS/apps/desktop
npm install

Configuration

Copy .env.example to .env and set any required environment variables (e.g., HERMES_API_KEY).
Ensure Hermes Agent is installed (curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash).

Running

npm run dev

or, on macOS, open the bundled .app from the releases page.

The app will register itself as a Hermes plugin under ~/.hermes/plugins/herald-os-bridge.

Real‑World Use

A user types “Find all my PDFs in Documents.” The following chain occurs:

Hermes forwards the intent to Herald OS.
ipc/catalog.ts::searchFiles is invoked.
backend/catalog.ts::searchFiles walks the Documents directory, filtering for .pdf.
The list is returned to Hermes, which displays it inline.

Code Health & Issues

The repository contains a secret‑scanning script (scripts/check-secrets.sh). Running it against the code base reports 0 secrets.

Severity (Low) – No hard‑coded secrets.
Severity (Low) – 74 Jest test files covering backend logic.

No other automated analysis blocks are present. The CI workflow (.github/workflows/ci.yml) runs tests and linting, indicating a basic quality gate.

The Bottom Line

Herald OS offers a straightforward, Electron‑based agent shell that plugs into Hermes. It is well‑structured, with clear separation between IPC, platform, and backend layers. The current alpha state means some edge cases may still fail, and installers are limited to macOS and a custom Linux build. For teams that already run Hermes Agent and need a quick desktop extension, Herald OS is a solid starting point.

What the analyser found

Deployment readiness

5/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

583 files

TypeScript268
TSX130
Markdown32
JSON29
Python28
Shell22

React

Module dependencies

The 10 most depended-upon modules of 429, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_apps_desktop_shared_ipc["ipc"] n1_apps_desktop_src_lib_cn["cn"] n2_ktop_src_components_ui_glass["glass"] n3_ps_desktop_src_store_backend["backend"] n4_ps_desktop_src_store_windows["windows"] n5_ktop_src_store_notifications["notifications"] n6_esktop_src_store_os_commands["os-commands"] n7_apps_desktop_src_store_shell["shell"] n8_apps_desktop_src_store_chat["chat"] n9_apps_desktop_electron_log["log"] n2_ktop_src_components_ui_glass --> n1_apps_desktop_src_lib_cn n3_ps_desktop_src_store_backend --> n0_apps_desktop_shared_ipc n8_apps_desktop_src_store_chat --> n3_ps_desktop_src_store_backend n8_apps_desktop_src_store_chat --> n5_ktop_src_store_notifications n5_ktop_src_store_notifications --> n0_apps_desktop_shared_ipc n5_ktop_src_store_notifications --> n3_ps_desktop_src_store_backend n7_apps_desktop_src_store_shell --> n0_apps_desktop_shared_ipc n4_ps_desktop_src_store_windows --> n3_ps_desktop_src_store_backend n4_ps_desktop_src_store_windows --> n7_apps_desktop_src_store_shell

Dependencies

3 of 30 declared dependencies are a major version behind. Resolved 29 of 30 against the registry.

Package	Declared	Latest	Behind
`@types/node`	22.20.3	26.2.0	4 major
`@nanostores/react`	1.1.0	2.0.1	1 major
`typescript`	6.0.3	7.0.2	1 major

Findings

LowSecret-shaped paths present; the code-health audit confirms or clears them scripts/check-secrets.sh

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high1

medium4

low2

Pin third-party GitHub Actions to a commit SHAhigh

.github/workflows

sigstore/cosign-installer@v3

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Enable Dependabot or Renovatemedium

3 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Pin the container base image by digestmedium

linux/image/Containerfile

quay.io/fedora/fedora-bootc:44

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/ci.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Set timeout-minutes on the workflow jobslow3 occurrences

.github/workflows/ci.yml

3 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Add the repository convention files this project lackslow3 occurrences

missing .editorconfig, .gitattributes, a formatter config

Without them one contributor's editor writes tabs into a Python file, a shell script commits with CRLF and fails in the container, and a notebook diff is unreviewable.

Fix: Add .editorconfig, .gitattributes with text=auto eol=lf, and a formatter config.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.