hermes-navigator 0.1.3

Multiverse Context Management — Hermes Navigator v1

Hermes Navigator — Multiverse Context Management

Hermes Navigator (hnavig) is the v1 implementation of the Hermes Navigator multiverse context management system. It gives William (and any local Hermes-class agent) instant orientation across 3 active development universes and ~120 terminals.

What It Does

• R1 — Universe Detection: Auto-detects which universe each terminal/tmux pane belongs to, using a priority chain of signals (env var → tmux name → git remote → path prefix → heuristic)
• R4 — Terminal Focus: Lists or switches tmux focus to a universe's terminal group
• R2 — Context Engine: Always-on background collector that builds a queryable snapshot of all terminal activity, scoped by universe
• R5 — Approval Queue: Proposed terminal actions flow through a review queue before execution
• R7 — Session Store: Named persistent sessions resumable from desktop or Telegram (/resume <name>)
• R8 — Skill Interface: Packaged as a Hermes skill, callable from any Hermes-class agent

Issue: jgwill/Miadi#265

---

Quick Start

# Install
cd runtime/hermes-navigator
pip install -e .

# Configure universes
mkdir -p ~/.hermes
cp examples/universes.yml ~/.hermes/universes.yml
# Edit ~/.hermes/universes.yml to match your universe roots

# Detect universe for current directory
hnavig detect

# Detect for a specific path
hnavig detect --cwd ~/src/Miadi

# List terminals for a universe
hnavig focus miadi

# Show context snapshot
hnavig context

# Start background daemon
hnavig daemon

# Install/start as a user service
hnavig service install --interval 15 --now

# Operator cockpit: know/enter existing tmux work
hnavig operator terminals
hnavig operator peek 7 --lines 80
hnavig operator attach 7
hnavig operator registry save
hnavig operator registry last-known
hnavig operator registry drift
hnavig operator checkpoint

Fast Demo Path For This Branch

Want to try the workspace/context slice without touching your real ~/.hermes state?

cd runtime/hermes-navigator
pip install -e .
./examples/demo-miadi-workspace.sh /usr/local/src/mightyeagle

What this does:

• sets HNAVIG_HOME to an isolated temp directory
• writes a one-universe config pointed at the repo you pass in
• captures a persisted context snapshot when the demo scene is frozen
• runs detect, ecf observe, scene activate, scene list, scene snapshot, and scene resume
• leaves the generated SQLite/files behind so you can inspect them after the run

You can also point the runtime at any alternate state directory yourself:

export HNAVIG_HOME=/tmp/hnavig-demo
hnavig detect --cwd /usr/local/src/mightyeagle

---

Configuration

~/.hermes/universes.yml — Universe Registry

universes:
  - name: miadi
    aliases: [main, mia]
    roots:
      - ~/src/Miadi
      - ~/work/Miadi
    remotes:
      - "github.com/jgwill/Miadi"
    env_var: "MIADI_UNIVERSE"
    tmux_pattern: "miadi-*"

  - name: aureon
    aliases: [aur]
    roots:
      - ~/src/aureon
    remotes:
      - "github.com/jgwill/aureon"
    tmux_pattern: "aureon-*"

See examples/universes.yml for a full example.

~/.hermes/config.yml — Navigator Config

mode: observer           # observer | controller
daemon_interval: 5.0     # seconds between context polls
session_db: ~/.hermes/sessions.db
context_log: ~/.hermes/context/log.ndjson
universes_config: ~/.hermes/universes.yml

See examples/config.yml for full options.

---

Commands

Detection

# Detect universe for current directory
hnavig detect

# Detect for specific cwd
hnavig detect --cwd ~/src/Miadi

# Detect for specific tmux pane
hnavig detect --pane %42

# Detect all panes in current tmux session
hnavig detect --all-panes

Focus (R4)

# List terminals for a universe (observer mode)
hnavig focus miadi

# List matching desktop terminal windows (Terminator/Konsole/etc.)
hnavig focus miadi --desktop
hnavig focus miadi --desktop --format json

# Activate a matching desktop window (controller mode + approval required)
hnavig mode controller
hnavig focus miadi --desktop --activate
hnavig focus miadi --desktop --activate --window-id 0x00eaf0d8

# Activate tmux focus to universe pane group (controller mode required)
hnavig mode controller
hnavig focus miadi

Operator Cockpit

These commands are the first "avoid context rot" surface. They are deliberately small: list the live tmux targets, inspect recent scrollback without attaching, and print the exact attach/switch commands before changing focus.

# List existing tmux sessions/panes and their attach commands
hnavig operator terminals
hnavig operator terminals --format json

# Inspect what is happening in a session or pane without attaching
hnavig operator peek 7 --lines 80
hnavig operator peek %7 --format json

# Print the commands for entering a target
hnavig operator attach 7

# Execute attach/switch from an interactive controller terminal
hnavig mode controller
hnavig operator attach 7 --run

# Persist terminal awareness as append-only JSONL
hnavig operator registry save
hnavig operator registry last-known
hnavig operator registry drift

# One read-only "know before entering" checkpoint
hnavig operator checkpoint
hnavig operator checkpoint --target 7 --peek-lines 20
hnavig operator checkpoint --format json

The registry is a read-only awareness surface after capture: save appends a timestamped snapshot under the Navigator state directory, last-known reads the newest persisted snapshot, and drift compares current tmux state with that snapshot. It stores observed tmux fields separately from inferred Navigator fields such as universe and attach commands.

operator checkpoint combines current terminals, the last-known registry metadata, drift summary, stale/last-seen hints, and safe entry commands. It does not capture scrollback unless --target is provided.

Context (R2)

# Show full context snapshot
hnavig context

# Filter by universe
hnavig context --universe miadi

# JSON output
hnavig context --format json

# Context from last 30 minutes
hnavig context --since 30m

Sessions (R7)

# Create a named session
hnavig session create aureon-refactor-2025

# Resume a session
hnavig session resume aureon-refactor-2025

# List all sessions
hnavig session list

# Archive a session
hnavig session archive aureon-refactor-2025

Mode

# Check current mode
hnavig mode

# Switch to active controller (enables tmux actions)
hnavig mode controller

# Switch back to observer (safe default)
hnavig mode observer

Daemon

# Start daemon (blocks; use & or a process manager)
hnavig daemon

# Start with custom poll interval
hnavig daemon --interval 10

# Scene launch opens a terminal/editor for a stored workspace. On systems with
# Terminator installed, Navigator prefers Terminator for new terminal windows.
hnavig scene activate /path/to/project --launch

# Daemon writes to:
#   ~/.hermes/context/latest.json    (last snapshot)
#   ~/.hermes/context/log.ndjson     (rolling log)
#   ~/.hermes/daemon.pid             (PID file)

User Service

Hermes Navigator should run as a user service, not a root/system service. It observes your user terminals, desktop windows, tmux panes, and user-owned state. The service writes a systemd user unit at ~/.config/systemd/user/hermes-navigator.service.

# Install and start immediately
hnavig service install --interval 15 --now

# If you want an explicit isolated runtime state:
hnavig service install --interval 15 --state-home ~/.local/state/hermes-navigator --now

# Control it later
hnavig service status
hnavig service restart
hnavig service stop
hnavig service uninstall

If ~/.hermes exists but is not accessible to your current user, Navigator falls back to ~/.local/state/hermes-navigator. If systemctl --user is unavailable, keep using hnavig daemon in a terminal or a local process manager until the desktop session imports user services.

Desktop App / Overlay

There is not yet a real floating Hermes window. The current working surfaces are:

• hnavig context — current daemon snapshot, including desktop windows
• hnavig focus <universe> --desktop — matching terminal windows
• hnavig session ... — named session continuity
• app/docs/miadi-agent/navigator — an interactive docs/mock UI that shows the intended overlay, approval queue, sessions, and Telegram continuity story

The desktop overlay is specified in rispecs/hermes-navigator/05-ui-surface.spec.md, but implementation remains the next product step.

---

Architecture Overview

universes.yml ──► UniverseDetector ──► ContextEngine ──► Daemon
                                              │
                                     ┌────────┼─────────┐
                                     │        │         │
                                 SessionStore  ApprovalQ  Focus
                                     │
                                    CLI (hnavig)

Data flow (Phase 1):

1. UniverseDetector reads universes.yml and detects universe identity for tmux panes
2. ContextEngine polls tmux and desktop windows every N seconds and builds ContextSnapshot
3. Daemon runs ContextEngine.start_continuous() and writes to ~/.hermes/
4. CLI commands query the daemon or directly invoke detection/focus

---

Integration with Hermes Skill Ecosystem

The navigator is packaged as a Hermes skill at skills/navigator.skill.yml. Any Hermes-class agent can load this manifest and call:

• navigator.focus(universe) — list or activate universe terminal group
• navigator.context(universe?, format?) — get context snapshot
• navigator.propose(action) — queue a terminal action for approval
• navigator.session.resume(name) — rehydrate a named session
• navigator.session.list() — list all sessions

See rispecs/hermes-navigator/04-skill-contract.spec.md for full action definitions.

---

Development

# Install in development mode
pip install -e ".[dev]"

# Run directly
python -m hermes_navigator.cli --help

Project Structure

runtime/hermes-navigator/
├── hermes_navigator/
│   ├── __init__.py         # package init
│   ├── models.py           # data models
│   ├── config.py           # config management
│   ├── universe_detector.py  # R1 — universe detection
│   ├── context_engine.py   # R2 — always-on context
│   ├── session_store.py    # R7 — named sessions (SQLite)
│   ├── focus.py            # R4 — terminal focus
│   ├── approval_queue.py   # R5 — action approval
│   ├── daemon.py           # background daemon
│   └── cli.py              # hnavig CLI
├── skills/
│   └── navigator.skill.yml  # Hermes skill manifest
├── examples/
│   ├── universes.yml        # example universe config
│   └── config.yml           # example navigator config
├── pyproject.toml
└── README.md

---

Specs

• Master: rispecs/hermes-navigator/00-hermes-navigator-master.spec.md
• Universe Detection: rispecs/hermes-navigator/01-universe-detection.spec.md
• Context Engine: rispecs/hermes-navigator/02-context-engine.spec.md
• Session Store: rispecs/hermes-navigator/03-session-store.spec.md
• Skill Contract: rispecs/hermes-navigator/04-skill-contract.spec.md
• UI Surface: rispecs/hermes-navigator/05-ui-surface.spec.md
• Daemon Lifecycle: rispecs/hermes-navigator/06-daemon-lifecycle.spec.md
• Mode And Safety: rispecs/hermes-navigator/07-mode-and-safety.spec.md
• Threat Model: rispecs/hermes-navigator/08-threat-model.spec.md
• Telegram Bridge: rispecs/hermes-navigator/09-telegram-bridge.spec.md
• Universe Relational Graph: rispecs/hermes-navigator/10-universe-relational-graph.spec.md
• Status: rispecs/hermes-navigator/STATUS.md