Metadata-Version: 2.4
Name: madqtt
Version: 0.1.0
Summary: Live TUI for the claude-prime MQTT/Mongo stream.
Project-URL: Homepage, https://github.com/MadnessEngineering/MadQTT
Project-URL: Repository, https://github.com/MadnessEngineering/MadQTT
Project-URL: Issues, https://github.com/MadnessEngineering/MadQTT/issues
Author-email: Dan Edens <danedens31@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: claude,mongodb,monitoring,mqtt,textual,tui
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Terminals
Requires-Python: >=3.11
Requires-Dist: aiomqtt>=2.3
Requires-Dist: pymongo>=4.6
Requires-Dist: textual>=0.80
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.6; extra == 'docs'
Requires-Dist: pymdown-extensions>=10.7; extra == 'docs'
Provides-Extra: web
Requires-Dist: textual-serve>=1.1; extra == 'web'
Description-Content-Type: text/markdown

# MadQTT

Live TUI for the [claude-prime hooks](../../../Anathesmelt/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

```bash
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

```bash
.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
```

## Documentation

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

```bash
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

| extra    | install                                        | what you get                                                       |
|----------|------------------------------------------------|--------------------------------------------------------------------|
| `[docs]` | `uv pip install -e '.[docs]'`                  | mkdocs-material site behind `--docs`                               |
| `[web]`  | `uv pip install -e '.[web]'`                   | `textual-serve "python -m madqtt"` exposes the TUI in a browser    |

## Dev

```bash
.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

| feature                              | shipped |
|--------------------------------------|---------|
| Sessions + Projects + Topics views   | v1.0    |
| Filter modal (project/topic/idle)    | v1.0    |
| Filter chips actually prune views    | v1.1    |
| Transcript viewer (`v`)              | v1.1    |
| Swarm chat pane (`c`)                | v1.1    |
| Write-back (`m`) to swarm/chat_in    | v1.2    |
| Fleet Mongo (`MADQTT_MONGO_URIS`)    | v1.2    |
| Browser exposure (textual-serve)     | v1.2    |
| Docs site + `--docs` CLI             | v1.3    |
| Persistent memory (UI state + log)   | v1.4    |
| tool_failure toast + fail/hr counter | v1.5    |
| Per-session task list (`T`)          | v1.6    |
| Pinned sessions + unread counts      | v1.7    |
| Inline transcript jumping            | v1.8    |
| Export filtered transcript (`e`)     | v1.9    |
| Global transcript search (`/`)       | v1.10   |
| Event inspector modal (`enter`, `i`) | v1.11   |
| Agent control panel (`a`)            | v1.12   |

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.
