🤝 Sidekick Badge Hook Status

Assessment of async badge update system

Hook Wiring

EventHandler
UserPromptSubmithandler.py user_prompt
PostToolUsehandler.py tool_use

Hooks are correctly wired in ~/.claude/settings.json

Debounce

120 seconds between badge updates

Lock file: /tmp/sidekick-badge-lock

Prevents spam during rapid prompts.

Hub Posting

Events posted to http://localhost:7895

Timeout: 2 seconds (non-blocking)

Gracefully handles hub being down.

LLM Badge Generation

Model: gemini/gemini-2.5-flash-lite

Now async via subprocess — hook returns immediately

subprocess.Popen([...badge_worker.py...], start_new_session=True)

✓ Fixed 2026-02-05

Tests

14 tests in supervisor/sidekick/hooks/test_handler.py

✓ Added 2026-02-05

Expectations

Basic format tests added (header, label).

No visual/screenshot expectations yet.

Future (low priority)

  • Screenshot badge rendering
  • End-to-end hook test

Summary

Component Status Issue
Hook wiring OK —
Hub posting OK —
Debounce OK —
LLM call OK Async subprocess (haiku, free)
Tests OK 14 tests passing
Expectations PARTIAL Basic format tests, no visual

Architecture

Claude Code Session
       │
       ▼ (Hook: UserPromptSubmit)
┌──────────────────────────────────────┐
│  handler.py user_prompt              │
│  ├─→ post_event() to Hub [2s timeout]│  ✅ Non-blocking
│  └─→ spawn_badge_worker()            │  ✅ Fire-and-forget
└──────────────────────────────────────┘
       │ (returns immediately)
       ▼
┌──────────────────────────────────────┐
│  badge_worker.py (subprocess)        │
│  ├─→ litellm.completion(haiku)       │  ~2s (free)
│  └─→ badge $'...'                    │  ✅ Sets badge
└──────────────────────────────────────┘

Files

FilePurpose
supervisor/sidekick/hooks/handler.pyMain hook handler
supervisor/sidekick/CLAUDE.mdDocumentation
~/.claude/settings.jsonHook wiring config
/tmp/sidekick-badge-lockDebounce lock file

Completed

  1. Make LLM call async — ✅ subprocess fire-and-forget
  2. Add basic tests — ✅ 14 tests passing
  3. Switch to haiku — ✅ free with Claude plan

Latency Analysis

ApproachLatencyNotes
Direct Anthropic SDK~1.0sBest possible
Subprocess + SDK (current)~2.1sNon-blocking
litellm~2.3s+0.5s import overhead
claude --print~5.0sHeavy CLI startup
Hot worker (future)~0.8sNo startup cost

See: lib/llm/benchmarks/CALLING_OVERHEAD.md

Future: Hot Worker

A persistent LLM worker would cut latency to ~0.8s:

┌─────────────────────────────────────┐
│  llm-worker (always running)        │
│  - anthropic client pre-initialized │
│  - Listens on unix socket or HTTP   │
└─────────────────────────────────────┘
         ▲ POST /complete
    handler.py → instant response

Options: add to hub, standalone worker, or unix socket daemon.

Generated: 2026-02-05 • rivus/supervisor/sidekick