MadQTT

Live TUI for the claude-prime hooks MQTT + MongoDB stream — turn the firehose into something a Mad Tinker can read.

┌ Sessions ─────────────┬ Session 4c0f8355 · madnessDesktop ──────────┐
│▶ 4c0f… madnessDesktop │ 01:06:36 Bash    grep -n private async…    │
│  ae97… element-dupe   │ 01:06:38 Bash    ✓ 1.5s                    │
│  9439… Inventorium    │ 01:06:42 Read    lib/api.ts                │
│  6465… madnessDesk    │ 01:06:44 Read    ✓ 2.2s                    │
│ failures: 3           │ 01:06:51 Bash    grep -rn ^export.func…    │
│ active:   4           │ 01:06:52 Bash    ✗ failure                 │
└───────────────────────┴─────────────────────────────────────────────┘
[s]essions [p]rojects [t]opics [c]hat [f]ilter [v]iew [m]sg [q]uit

Install

pip install madqtt          # from PyPI
madqtt                      # run it

Or for local dev from a checkout:

uv venv .venv
uv pip install -p .venv/bin/python -e .

If your global uv cache has root-owned subdirs from a past sudo install, route around it: UV_CACHE_DIR=.uv-cache uv pip install -p .venv/bin/python -e .

Run

.venv/bin/python -m madqtt                        # live: broker + Mongo backfill
.venv/bin/python -m madqtt --replay dataset1.txt  # replay a mosquitto_sub -v capture
.venv/bin/python -m madqtt --host eaws --port 1883

Where the data comes from

MadQTT is the consumer. It renders a stream that something else has to produce: Claude Code hooks that publish to an MQTT broker and (optionally) mirror to MongoDB. No producer running → empty timeline.

The contract MadQTT subscribes to:

<device> is the DeNa env var on the publishing host (default macbook). The full topic + payload reference is in the docs (--docs, below).

Just want to see it work? No broker, no Mongo, no hooks needed — replay a captured stream:

madqtt --replay dataset1.txt   # a mosquitto_sub -v capture, ships in the repo

Wiring up a live producer. The reference producer is the claude-prime hook set in the Madness workshop — a bundle of Claude Code PreToolUse/PostToolUse/SessionStart/… hooks that mosquitto_pub the events above. It's workshop-coupled (dvttestkit, a hooks_config.json of feature flags), so treat it as a worked example of the contract rather than a drop-in: any hook that publishes those topics in that shape will light up MadQTT. Point it at your broker with:

export MADNESS_MQTT_HOST=your-broker     # default localhost
export MADNESS_MQTT_PORT=1883
export CLAUDE_MONGO_URI=mongodb://localhost:27017/   # optional backfill
madqtt

Documentation

Everything else — keys, configuration, architecture, the full topic & payload reference — lives in the docs site:

uv pip install -p .venv/bin/python -e '.[docs]'
.venv/bin/python -m madqtt --docs

Spawns mkdocs serve on a free port and opens your browser.

Optional extras

Dev

.venv/bin/python -m pytest tests/ -q          # parser regression against dataset1.txt
.venv/bin/python scripts/smoke_replay.py      # headless: all views, SVG captures
.venv/bin/python scripts/smoke_live.py        # live: backfill + 4 synthetic publishes
.venv/bin/python -m mkdocs build --strict     # build docs site to ./site

Project layout

madqtt/                package
├── events.py          Event dataclass + topic parser
├── store.py           EventStore + ring + per-session/topic rollups + Mongo backfill
├── ingest.py          aiomqtt subscriber + replay
├── app.py             Textual App, key bindings, view switching
├── docs.py            --docs implementation
├── config.py          env-var Config
└── widgets/           sessions, projects, topics, chat, filter, transcript, message
docs/                  mkdocs-material site (built behind --docs)
tests/                 parser regression
scripts/               smoke_replay.py, smoke_live.py

Status

Roadmap candidates: "open cwd in editor" key, per-tool aggregate stats view.

Persistent memory

Two files under ~/.madqtt/ (override with MADQTT_STATE_DIR, disable with MADQTT_NO_PERSIST=1):

• state.json — last view, filter chips, idle toggle, last selected session. Restored on launch, saved on quit + every 30s.
• events.jsonl — append-only mirror of every Event. Replayed into the ring on startup so the timeline survives broker + Mongo being down.