Clembot HUD

Most agent observability platforms show chronological tool call transcripts: a linear, 2,000-line firehose of bash, read_file, and replace_file_content logs. When coding agents run for hours or execute across parallel lanes, transcripts create immense cognitive noise without answering the fundamental questions: Where in the architecture is the agent working? Is it thrashing? Has it touched finished code?

Clembot HUD is an architecture-grounded observability HUD and state machine for Clembot. Instead of replaying raw conversation transcripts, it binds agent activity directly to a directed graph of architectural components, file globs, and living invariants.

Three Pillars of Architectural Telemetry

                       ┌────────────────────────────────────────┐
                       │          Architectural Invariants      │
                       │     (5–9 Components, Needs, Globs)     │
                       └───────────────────▲────────────────────┘
                                           │
┌────────────────────────┐     ┌───────────┴────────────┐     ┌────────────────────────┐
│   Declared State       │ ──► │  Local Event Relay     │ ◄── │   Filesystem Reality   │
│  PLAN.md ([ ], [~], [x])│     │  (SSE Broadcast :5330) │     │  (fs.watch, Heatmap)   │
└────────────────────────┘     └────────────────────────┘     └────────────────────────┘

1. Architecture over Transcripts:

   • Work is categorized into 5–9 durable system components ({#storage}, {#commands}, {#cli}, {#tests}).
   • Components declare explicit file ownership patterns (files: [src/store.*]) and directed dependencies (needs: [storage]).
   • The UI visualizes a living DAG rather than an endless chat log.

2. Filesystem Grounding vs. Declared Intent:

   • Agents often hallucinate their status or batch plan updates at the end of a session.
   • Clembot HUD watches the underlying filesystem (fs.watch) alongside local Claude Code hook events (PreToolUse, PostToolUse).
   • If an agent touches a file inside src/store.*, the Storage card lights up and records a heat pulse regardless of what the prompt claims.

3. Scope-Drift & Regression Detection:

   • When a component is completed ([x]), it enters a stable state.
   • If an agent working on a downstream task begins modifying files owned by an upstream, completed component, the HUD flags the card with an active Revising · <file> pulse.
   • Supervisors and operators can immediately spot accidental regressions or out-of-scope refactor loops before commits occur.

The Clembot CLI Integration (clembot hud)

Observability is built directly into Clembot’s CLI as an opt-in sidecar:

# Launch the real-time architectural HUD for the current workspace
clembot hud

# Launch with the experimental 3D Kitchen view on port 4780
clembot hud --kitchen

# Run headless or bind to a custom daemon port
clembot hud --port 5340 --no-open

Fault-Tolerant Sidecar Design

• Zero Dependency Core: The local daemon runs without external cloud subscriptions or database overhead.
• Cross-Platform Hardening: Wrapped with safe Windows process launching (cmd /c start) to prevent unhandled spawn ENOENT runtime crashes.
• Graceful Termination: Captures SIGINT / SIGTERM and automatically cleans up background telemetry daemons without dangling orphaned Node processes.

Verified Evaluation Matrix

Evaluated in clean-room testing across a 4-component CLI application: