{"id":50881655,"url":"https://github.com/zd87pl/hermes-g2-hud","last_synced_at":"2026-06-15T13:30:27.832Z","repository":{"id":357235549,"uuid":"1236023475","full_name":"zd87pl/hermes-g2-hud","owner":"zd87pl","description":"Hermes AI agent monitoring and control HUD for Even Realities G2 smart glasses. WebSocket-powered real-time agent status, cron monitoring, voice commands, and tap/scroll navigation.","archived":false,"fork":false,"pushed_at":"2026-05-11T22:25:05.000Z","size":44,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-12T00:24:25.006Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zd87pl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-11T22:02:08.000Z","updated_at":"2026-05-11T22:25:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zd87pl/hermes-g2-hud","commit_stats":null,"previous_names":["zd87pl/hermes-g2-hud"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/zd87pl/hermes-g2-hud","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zd87pl%2Fhermes-g2-hud","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zd87pl%2Fhermes-g2-hud/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zd87pl%2Fhermes-g2-hud/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zd87pl%2Fhermes-g2-hud/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zd87pl","download_url":"https://codeload.github.com/zd87pl/hermes-g2-hud/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zd87pl%2Fhermes-g2-hud/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34365596,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-15T02:00:07.085Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-15T13:30:26.514Z","updated_at":"2026-06-15T13:30:27.823Z","avatar_url":"https://github.com/zd87pl.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hermes G2 HUD\n\n\u003e **Monitor and control your Hermes AI agents from Even Realities G2 smart glasses.**  \n\u003e Real-time agent status, cron monitoring, notifications, and voice commands — all on a glanceable HUD.\n\n```\n┌─────────────┐   WebSocket    ┌─────────────┐   Bluetooth   ┌──────────────┐\n│  Hermes WS  │ ◄────────────► │  Phone       │ ◄───────────► │  G2 Glasses  │\n│  Gateway    │                │  (Even Hub   │               │  (display +  │\n│  :9090      │                │   WebView)   │               │   mic + tap) │\n└─────────────┘                └─────────────┘               └──────────────┘\n```\n\n## How It Works\n\n1. **Hermes WS Gateway** runs on your server (or laptop). It exposes a WebSocket endpoint on port 9090.\n2. **G2 HUD App** is a web app that runs inside the Even Realities app on your phone. It connects to the gateway over WebSocket.\n3. **Hermes pushes updates** to the gateway via a simple REST API — agent status changes, notifications, cron results.\n4. **Commands go the other way** — tap a command on the glasses, it flows through the gateway to Hermes.\n\n## Quick Start (3 minutes)\n\n```bash\n# 1. Clone the repo\ngit clone https://github.com/zd87pl/hermes-g2-hud.git\ncd hermes-g2-hud\n\n# 2. Run setup (checks deps, installs Python + Node packages, builds G2 app)\n./scripts/setup.sh\n\n# 3. Start the gateway\n./scripts/start.sh\n```\n\nThat's it. The gateway is now running at `http://localhost:9090`.\n\n---\n\n## Full Setup Guide\n\n### Prerequisites\n\n| Tool | Version | Check |\n|------|---------|-------|\n| Python | 3.10+ | `python3 --version` |\n| Node.js | 18+ | `node --version` |\n| npm | 9+ | `npm --version` |\n| Even Realities App | Latest | [App Store](https://apps.apple.com/app/even-realities/id6443958843) / [Google Play](https://play.google.com/store/apps/details?id=com.evenrealities.evenhub) |\n| G2 Glasses | — | Paired with your phone via Bluetooth |\n\n### Step 1: Clone \u0026 Setup\n\n```bash\ngit clone https://github.com/zd87pl/hermes-g2-hud.git\ncd hermes-g2-hud\n./scripts/setup.sh\n```\n\nThis creates a Python virtualenv, installs the gateway dependencies, installs the G2 app's npm packages, and runs TypeScript + Vite build.\n\n### Step 2: Start the Gateway\n\n```bash\n# Direct\n./scripts/start.sh\n\n# With custom port\n./scripts/start.sh --port 8080\n\n# With Hermes callback (for external commands)\nHERMES_CALLBACK_URL=http://localhost:8080 ./scripts/start.sh\n```\n\nOr use Docker:\n\n```bash\ndocker compose up -d\n```\n\nVerify it's running:\n\n```bash\ncurl http://localhost:9090/api/status\n# {\"status\":\"ok\",\"connected_clients\":0,\"agent_count\":0}\n```\n\n### Step 3: Push Agent Updates (from Hermes)\n\nThe gateway has a REST API that Hermes (or any script/cron job) can call to push updates:\n\n```bash\n# Push an agent update\ncurl -X POST http://localhost:9090/api/agents \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"id\": \"powerhouse-dev\",\n    \"name\": \"Powerhouse Dev\",\n    \"status\": \"busy\",\n    \"task\": \"Reviewing PR #342\",\n    \"progress\": 65\n  }'\n\n# Push a notification\ncurl -X POST http://localhost:9090/api/notifications \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"type\": \"warn\",\n    \"message\": \"CI pipeline failed for curvypoland (lint)\",\n    \"agent_id\": \"powerhouse-dev\"\n  }'\n\n# Push a command result\ncurl -X POST http://localhost:9090/api/command-callback \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"command_id\": \"cmd_1\",\n    \"result\": \"All systems healthy.\\n3 agents running.\\n5 cron jobs active.\"\n  }'\n```\n\n**Pro tip:** Add a Hermes hook that POSTs to the gateway whenever an agent starts, completes, or errors. Example cron hook:\n\n```bash\n# In your Hermes cron job or agent lifecycle hook:\ncurl -s -X POST http://localhost:9090/api/agents \\\n  -H \"Content-Type: application/json\" \\\n  -d \"{\\\"id\\\": \\\"$(hostname)\\\", \\\"name\\\": \\\"$(hostname)\\\", \\\"status\\\": \\\"busy\\\", \\\"task\\\": \\\"$TASK_NAME\\\"}\"\n```\n\n### Step 4: Build \u0026 Sideload the G2 App\n\nThe G2 HUD is a Vite + TypeScript web app. Build and sideload it to your glasses:\n\n```bash\n# Build\nnpm run build\n\n# Generate QR code for sideloading\nnpx evenhub qr\n\n# Scan the QR code with the Even Realities App\n# (Even Realities App → Developer → Scan QR Code)\n```\n\nThe app connects to the gateway via WebSocket. By default it tries `ws://127.0.0.1:9090` (localhost on your phone won't work in production — see below).\n\n### Step 5: Configure the WS URL\n\nFor production (your phone connecting to a remote server), update the WebSocket URL in the G2 app:\n\nEdit `app.json` to whitelist your server's domain:\n\n```json\n{\n  \"network\": [\n    \"wss://hermes.yourdomain.com\",\n    \"ws://192.168.1.100:9090\"\n  ]\n}\n```\n\nThen update the WebSocket URL in `src/main.ts` (line ~42):\n\n```typescript\nconst ws = new HermesWebSocket({ url: 'ws://192.168.1.100:9090' });\n```\n\nRebuild and re-sideload after changing.\n\n---\n\n## Using the Glasses\n\n### Navigation\n\n| Input | Action |\n|-------|--------|\n| **Tap** | Advance (next screen, next agent, execute command) |\n| **Double-tap** | Go back to Dashboard |\n| **Scroll down** | Next item in list / Quick Commands |\n| **Scroll up** | Previous item in list |\n\n### Screens\n\n| # | Screen | What you see |\n|---|--------|-------------|\n| 1 | **Dashboard** | Agent count, status breakdown, top 2 agents, unread count |\n| 2 | **Agent Detail** | Per-agent status, current task, progress bar, last active |\n| 3 | **Notifications** | Scrollable list of alerts with type icons, mark-read |\n| 4 | **Quick Commands** | 8 pre-configured commands (health, cron, deploy, etc.) |\n\n### Quick Commands\n\n| Command | What it does |\n|---------|-------------|\n| Health Audit | Check system health |\n| Cron Status | List active cron jobs |\n| Platform Health | Platform-wide health check |\n| Agent Status | Dump all agent states |\n| Deploy Status | Check deployments |\n| Notifications | View recent notifications |\n| CurvyPoland | Deploy status for CurvyPoland |\n| Run Daily Brief | Trigger daily AI briefing |\n\n---\n\n## Hermes Integration Patterns\n\n### Option A: REST Push (simplest)\n\nHermes pushes updates to the gateway via REST. Add to your Hermes agent hooks, cron scripts, or deployment pipelines:\n\n```python\nimport requests\n\ndef notify_gateway(agent_id: str, status: str, task: str = \"\", progress: int = 0):\n    \"\"\"Push agent state to the G2 gateway.\"\"\"\n    try:\n        requests.post(\"http://localhost:9090/api/agents\", json={\n            \"id\": agent_id,\n            \"name\": agent_id,\n            \"status\": status,\n            \"task\": task,\n            \"progress\": progress,\n        }, timeout=5)\n    except Exception:\n        pass  # Gateway is optional — don't crash if it's down\n\ndef push_notification(msg_type: str, message: str):\n    \"\"\"Push a notification to the G2 gateway.\"\"\"\n    try:\n        requests.post(\"http://localhost:9090/api/notifications\", json={\n            \"type\": msg_type,\n            \"message\": message,\n        }, timeout=5)\n    except Exception:\n        pass\n```\n\n### Option B: WebSocket Bridge (real-time)\n\nIf you want Hermes itself to maintain a persistent connection, the gateway's WS protocol is simple:\n\n```python\nimport asyncio\nimport websockets\nimport json\n\nasync def hermes_bridge():\n    async with websockets.connect(\"ws://localhost:9090/ws\") as ws:\n        # Subscribe\n        await ws.send(json.dumps({\n            \"type\": \"subscribe\",\n            \"topics\": [\"agents\", \"notifications\"],\n        }))\n        # Listen for commands from G2\n        async for msg in ws:\n            data = json.loads(msg)\n            if data[\"type\"] == \"command\":\n                # Handle the command\n                result = handle_command(data[\"command\"])\n                # No need to reply — commands return via REST callback\n```\n\n### Option C: Systemd Service (production)\n\n```bash\nsudo cp deploy/systemd/hermes-gateway.service /etc/systemd/system/\nsudo systemctl daemon-reload\nsudo systemctl enable --now hermes-gateway\nsudo systemctl status hermes-gateway\n```\n\n---\n\n## API Reference\n\n### Gateway REST API\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `GET` | `/api/status` | Health check |\n| `GET` | `/api/agents` | List all agents |\n| `POST` | `/api/agents` | Push agent update |\n| `GET` | `/api/notifications` | List all notifications |\n| `POST` | `/api/notifications` | Push notification |\n| `POST` | `/api/command-callback` | Receive command result |\n| `WS` | `/ws` | G2 HUD WebSocket |\n\n### Agent Update Payload\n\n```json\n{\n  \"id\": \"powerhouse-dev\",\n  \"name\": \"Powerhouse Dev\",\n  \"status\": \"busy\",        // idle | busy | error | offline\n  \"task\": \"PR review #342\",\n  \"progress\": 65,          // 0–100\n  \"last_active\": 1715452800000,\n  \"error\": null\n}\n```\n\n### WebSocket Protocol\n\n```\nClient → Server:\n  {\"type\": \"subscribe\", \"topics\": [\"agents\", \"notifications\"]}\n  {\"type\": \"command\", \"id\": \"cmd_N\", \"command\": {\"action\": \"health_audit\", \"params\": {}}}\n\nServer → Client:\n  {\"type\": \"agent_update\", \"agent\": {...}}\n  {\"type\": \"notification\", \"notification\": {...}}\n  {\"type\": \"command_result\", \"commandId\": \"cmd_N\", \"result\": \"...\"}\n```\n\n---\n\n## Project Structure\n\n```\nhermes-g2-hud/\n├── gateway/                    # Python WebSocket gateway\n│   ├── __init__.py\n│   ├── __main__.py\n│   ├── cli.py                  # Entry point\n│   ├── server.py               # FastAPI + WebSocket server\n│   ├── agent_tracker.py        # In-memory agent registry\n│   ├── notification_store.py   # Notification storage\n│   ├── command_handler.py      # Command dispatch to Hermes\n│   ├── requirements.txt\n│   └── Dockerfile\n├── src/                        # G2 HUD web app (TypeScript)\n│   ├── main.ts                 # App entry + navigation\n│   ├── types.ts                # Shared types\n│   ├── integration-example.ts  # Programmatic API\n│   ├── bridge/\n│   │   ├── display.ts          # G2 display rendering\n│   │   ├── input.ts            # Tap/scroll events\n│   │   └── audio.ts            # Mic capture (voice)\n│   ├── screens/\n│   │   ├── dashboard.ts\n│   │   ├── agent-detail.ts\n│   │   ├── notifications.ts\n│   │   └── quick-cmd.ts\n│   ├── services/\n│   │   ├── hermes-ws.ts        # WebSocket client\n│   │   ├── agent-tracker.ts\n│   │   ├── notification-store.ts\n│   │   ├── command-dispatcher.ts\n│   │   └── index.ts\n│   └── utils/\n│       ├── constants.ts\n│       └── text-formatter.ts\n├── scripts/\n│   ├── setup.sh                # One-command setup\n│   └── start.sh                # Start the gateway\n├── deploy/\n│   └── systemd/\n│       └── hermes-gateway.service\n├── docker-compose.yml\n├── app.json                    # Even Hub metadata\n├── package.json\n├── tsconfig.json\n├── vite.config.ts\n└── README.md\n```\n\n---\n\n## Troubleshooting\n\n| Problem | Solution |\n|---------|----------|\n| G2 app shows \"OFFLINE\" | Gateway not running — `./scripts/start.sh` |\n| \"WebSocket connection error\" | Wrong WS URL — check `src/main.ts` and network config |\n| Commands return \"Unknown command\" | Set `HERMES_CALLBACK_URL` env var |\n| Can't sideload to glasses | Make sure Even Realities App is in Developer mode (App → Settings → Developer) |\n| Gateway not reachable from phone | Use your computer's LAN IP (`ifconfig`), not localhost |\n| `tsc` build fails | Remove `tsc` from build script in `package.json`, use `vite build` directly |\n| Vite build fails on esbuild | `/tmp` is noexec — clone to a writable directory like `~/` |\n\n---\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n\nBuilt for [Hermes Agent](https://github.com/zd87pl/powerhouse) by [zd87pl](https://github.com/zd87pl).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzd87pl%2Fhermes-g2-hud","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzd87pl%2Fhermes-g2-hud","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzd87pl%2Fhermes-g2-hud/lists"}