# muxplex Distribution Packaging Plan

> **Execution:** Use the subagent-driven-development workflow to implement this plan.

**Goal:** Package muxplex as a distributable Python tool installable via `uvx` or `uv tool install` from `git+https://github.com/bkrabach/muxplex`. Single-port server (no Caddy required), CLI entry point, systemd service support.

**Architecture:** The `coordinator/` package is renamed to `muxplex/`, the `frontend/` directory moves inside it as package data, and a WebSocket proxy route replaces Caddy's only remaining job (proxying `/terminal/ws` to ttyd). A new `cli.py` provides the `muxplex` command with `serve` and `install-service` subcommands.

**Tech Stack:** Python 3.11+, FastAPI, uvicorn, websockets, hatchling (build backend)

**Not in scope:** GitHub repo creation, git submodule setup, PyPI publishing — handled separately after coding tasks complete.

---

### Task 1: Rename `coordinator/` → `muxplex/` and move `frontend/` inside

**Files:**
- Rename: `coordinator/` → `muxplex/` (all files move)
- Move: `frontend/` → `muxplex/frontend/` (becomes package data)
- Modify: every `.py` file under `muxplex/` (import rewrite)
- Modify: `pyproject.toml` (testpaths)

This is a purely mechanical rename — no behavior changes, no new features. Every other task depends on this layout being in place.

**Step 1: Move the directories**

```bash
cd /home/bkrabach/dev/web-tmux/muxplex
mv coordinator muxplex
mv frontend muxplex/frontend
```

**Step 2: Rewrite all `coordinator` → `muxplex` in Python source files**

There are exactly 6 import lines in source files that need updating:

In `muxplex/bells.py`:
```python
# line 20 — old
from coordinator.sessions import run_tmux
# new
from muxplex.sessions import run_tmux

# line 21 — old
from coordinator.state import empty_bell
# new
from muxplex.state import empty_bell
```

In `muxplex/main.py`:
```python
# line 22 — old
from coordinator.bells import apply_bell_clear_rule, process_bell_flags
# new
from muxplex.bells import apply_bell_clear_rule, process_bell_flags

# line 23 — old
from coordinator.sessions import (
# new
from muxplex.sessions import (

# line 31 — old
from coordinator.state import (
# new
from muxplex.state import (

# line 40 — old
from coordinator.ttyd import kill_orphan_ttyd, kill_ttyd, spawn_ttyd, TTYD_PORT
# new
from muxplex.ttyd import kill_orphan_ttyd, kill_ttyd, spawn_ttyd, TTYD_PORT
```

**Step 3: Rewrite all `coordinator` → `muxplex` in test files**

There are 25 import references and 35 `monkeypatch.setattr("coordinator.*")` calls across 7 test files. Use sed for bulk replacement in each file:

```bash
cd /home/bkrabach/dev/web-tmux/muxplex
# Replace in all Python files under muxplex/ (source + tests)
find muxplex -name '*.py' -exec sed -i 's/coordinator\./muxplex./g' {} +
find muxplex -name '*.py' -exec sed -i 's/from muxplex\.sessions/from muxplex.sessions/g' {} +
```

But verify these specific files have the correct replacements (every occurrence of `coordinator.` becomes `muxplex.`):

- `muxplex/tests/test_api.py` — 27 monkeypatch + 7 import references
- `muxplex/tests/test_bells.py` — 2 imports
- `muxplex/tests/test_integration.py` — 4 imports + 4 monkeypatch
- `muxplex/tests/test_sessions.py` — 2 imports
- `muxplex/tests/test_state.py` — 3 imports + 2 monkeypatch
- `muxplex/tests/test_ttyd.py` — 2 imports + 2 monkeypatch

**Step 4: Update `_FRONTEND_DIR` path in `muxplex/main.py`**

The static file path must change since `frontend/` is now inside the package:

```python
# OLD (line 344 of muxplex/main.py):
_FRONTEND_DIR = pathlib.Path(__file__).parent.parent / "frontend"

# NEW:
_FRONTEND_DIR = pathlib.Path(__file__).parent / "frontend"
```

**Step 5: Update frontend path references in test files**

Two test files compute the path to `frontend/` relative to their own location. After the restructure, the traversal changes from `.parent.parent.parent / "frontend"` (3 levels up) to `.parent.parent / "frontend"` (2 levels up, since tests are now at `muxplex/tests/` and frontend is at `muxplex/frontend/`):

In `muxplex/tests/test_frontend_css.py` (line 5):
```python
# OLD:
CSS_PATH = pathlib.Path(__file__).parent.parent.parent / "frontend" / "style.css"

# NEW:
CSS_PATH = pathlib.Path(__file__).parent.parent / "frontend" / "style.css"
```

In `muxplex/tests/test_frontend_html.py` (line 7):
```python
# OLD:
HTML_PATH = pathlib.Path(__file__).parent.parent.parent / "frontend" / "index.html"

# NEW:
HTML_PATH = pathlib.Path(__file__).parent.parent / "frontend" / "index.html"
```

**Step 6: Move `spike_bell_flag.py` out of the package**

The `spike_bell_flag.py` file is a one-off dev spike — it should not ship in the wheel:

```bash
mv muxplex/spike_bell_flag.py scripts/spike_bell_flag.py
```

**Step 7: Update `pyproject.toml` testpaths**

```toml
# OLD:
testpaths = ["coordinator/tests"]

# NEW:
testpaths = ["muxplex/tests"]
```

**Step 8: Run all tests to verify nothing broke**

```bash
cd /home/bkrabach/dev/web-tmux/muxplex
python -m pytest muxplex/tests/ --ignore=muxplex/tests/test_integration.py -q 2>&1 | tail -10
```
Expected: **169 passed** (same count as before)

```bash
node --test muxplex/frontend/tests/test_app.mjs 2>&1 | tail -3
```
Expected: **pass 136, fail 0**

```bash
node --test muxplex/frontend/tests/test_terminal.mjs 2>&1 | tail -3
```
Expected: **pass, fail 0**

**Step 9: Commit**

```bash
git add -A && git commit -m "refactor: rename coordinator → muxplex package, move frontend inside as package data"
```

---

### Task 2: Add WebSocket proxy route to replace Caddy

**Files:**
- Modify: `muxplex/main.py` (add WebSocket route + update bell hook port)
- Modify: `muxplex/tests/test_api.py` (add route-exists test)
- Modify: `requirements.txt` (add websockets)

This eliminates Caddy as a runtime dependency. The FastAPI app becomes the single-port server, proxying `/terminal/ws` to ttyd at `ws://localhost:7682/ws`.

**Step 1: Write the failing test**

Add to the end of `muxplex/tests/test_api.py`:

```python
# ---------------------------------------------------------------------------
# WebSocket proxy route
# ---------------------------------------------------------------------------


def test_terminal_ws_route_exists():
    """The app must have a WebSocket route registered at /terminal/ws."""
    from muxplex.main import app

    ws_routes = [
        r for r in app.routes
        if hasattr(r, "path") and r.path == "/terminal/ws"
    ]
    assert len(ws_routes) == 1, "Expected exactly one /terminal/ws route"
```

**Step 2: Run test to verify it fails**

```bash
cd /home/bkrabach/dev/web-tmux/muxplex
python -m pytest muxplex/tests/test_api.py::test_terminal_ws_route_exists -v
```
Expected: **FAIL** — no `/terminal/ws` route exists yet.

**Step 3: Add `websockets` dependency to requirements.txt**

```
websockets>=11.0
```

Install it:
```bash
pip install websockets>=11.0
```

**Step 4: Add the WebSocket proxy route to `muxplex/main.py`**

Add these imports near the top (after the existing imports):

```python
from fastapi import WebSocket
import websockets
```

Note: `asyncio` is already imported. `WebSocket` goes on the same line as the existing `FastAPI, HTTPException` import:

```python
# Change this line:
from fastapi import FastAPI, HTTPException

# To:
from fastapi import FastAPI, HTTPException, WebSocket
```

Add a `SERVER_PORT` config variable near `POLL_INTERVAL` (around line 46):

```python
SERVER_PORT: int = int(os.environ.get("MUXPLEX_PORT", "8088"))
```

Add the WebSocket route **after** the last API route (`setup_hooks`) but **before** the static file mount:

```python
# ---------------------------------------------------------------------------
# WebSocket proxy — relay browser ↔ ttyd (replaces Caddy reverse-proxy)
# ---------------------------------------------------------------------------


@app.websocket("/terminal/ws")
async def proxy_terminal_ws(websocket: WebSocket) -> None:
    """Proxy browser WebSocket to ttyd for terminal I/O.

    Accepts with subprotocol 'tty' (required by ttyd), connects to the local
    ttyd instance, and relays frames bidirectionally until either side closes.
    """
    await websocket.accept(subprotocol="tty")
    ttyd_url = f"ws://localhost:{TTYD_PORT}/ws"

    try:
        async with websockets.connect(ttyd_url, subprotocols=["tty"]) as ttyd_ws:

            async def client_to_ttyd() -> None:
                try:
                    while True:
                        msg = await websocket.receive()
                        if msg.get("type") == "websocket.disconnect":
                            break
                        if msg.get("bytes") is not None:
                            await ttyd_ws.send(msg["bytes"])
                        elif msg.get("text") is not None:
                            await ttyd_ws.send(msg["text"])
                except Exception:
                    pass

            async def ttyd_to_client() -> None:
                try:
                    async for message in ttyd_ws:
                        if isinstance(message, bytes):
                            await websocket.send_bytes(message)
                        else:
                            await websocket.send_text(message)
                except Exception:
                    pass

            await asyncio.gather(client_to_ttyd(), ttyd_to_client())
    except Exception:
        pass
    finally:
        try:
            await websocket.close()
        except Exception:
            pass
```

**Step 5: Update the alert-bell hook URLs from port 8099 → `SERVER_PORT`**

There are exactly two hardcoded `8099` references in `muxplex/main.py`. Both are in the `run-shell` curl command for the tmux alert-bell hook.

Line ~148 (in `lifespan`):
```python
# OLD:
"run-shell 'curl -sfo /dev/null -X POST http://localhost:8099/api/sessions/#{session_name}/bell || true'",

# NEW:
f"run-shell 'curl -sfo /dev/null -X POST http://localhost:{SERVER_PORT}/api/sessions/#{{session_name}}/bell || true'",
```

Line ~333 (in `setup_hooks`):
```python
# OLD:
"run-shell 'curl -sfo /dev/null -X POST http://localhost:8099/api/sessions/#{session_name}/bell || true'",

# NEW:
f"run-shell 'curl -sfo /dev/null -X POST http://localhost:{SERVER_PORT}/api/sessions/#{{session_name}}/bell || true'",
```

Note the double-braces `#{{session_name}}` — in an f-string, `{{` produces a literal `{`, so the tmux variable `#{session_name}` is preserved.

**Step 6: Run tests to verify pass**

```bash
cd /home/bkrabach/dev/web-tmux/muxplex
python -m pytest muxplex/tests/test_api.py::test_terminal_ws_route_exists -v
```
Expected: **PASS**

Also run the full test suite to ensure nothing broke:
```bash
python -m pytest muxplex/tests/ --ignore=muxplex/tests/test_integration.py -q 2>&1 | tail -5
```
Expected: **170 passed** (169 + 1 new)

**Step 7: Commit**

```bash
git add -A && git commit -m "feat: add WebSocket proxy route to replace Caddy, update bell hook port to configurable SERVER_PORT"
```

---

### Task 3: Create `muxplex/cli.py` entry point and `muxplex/__main__.py`

**Files:**
- Create: `muxplex/cli.py`
- Create: `muxplex/__main__.py`
- Create: `muxplex/tests/test_cli.py`

The CLI is the user-facing interface: `muxplex` runs the server, `muxplex install-service` writes a systemd unit file.

**Step 1: Write the failing tests**

Create `muxplex/tests/test_cli.py`:

```python
"""Tests for muxplex/cli.py — CLI entry point."""

import os
import sys
from pathlib import Path
from unittest.mock import patch

import pytest


def test_cli_module_importable():
    """muxplex.cli must be importable."""
    from muxplex.cli import main  # noqa: F401


def test_main_calls_serve_by_default():
    """Calling main() with no args must invoke serve()."""
    from muxplex.cli import main

    with patch("muxplex.cli.serve") as mock_serve:
        with patch("sys.argv", ["muxplex"]):
            main()
        mock_serve.assert_called_once_with(host="0.0.0.0", port=8088)


def test_main_passes_custom_host_and_port():
    """main() with --host/--port must forward them to serve()."""
    from muxplex.cli import main

    with patch("muxplex.cli.serve") as mock_serve:
        with patch("sys.argv", ["muxplex", "--host", "127.0.0.1", "--port", "9000"]):
            main()
        mock_serve.assert_called_once_with(host="127.0.0.1", port=9000)


def test_main_install_service_subcommand():
    """main() with 'install-service' must invoke install_service()."""
    from muxplex.cli import main

    with patch("muxplex.cli.install_service") as mock_install:
        with patch("sys.argv", ["muxplex", "install-service"]):
            main()
        mock_install.assert_called_once_with(system=False)


def test_main_install_service_system_flag():
    """main() with 'install-service --system' passes system=True."""
    from muxplex.cli import main

    with patch("muxplex.cli.install_service") as mock_install:
        with patch("sys.argv", ["muxplex", "install-service", "--system"]):
            main()
        mock_install.assert_called_once_with(system=True)


def test_install_service_user_mode_writes_unit_file(tmp_path, monkeypatch):
    """install_service(system=False) writes a unit file to ~/.config/systemd/user/."""
    from muxplex.cli import install_service

    fake_home = tmp_path / "home"
    fake_home.mkdir()
    monkeypatch.setattr(Path, "home", staticmethod(lambda: fake_home))

    install_service(system=False)

    unit_path = fake_home / ".config" / "systemd" / "user" / "muxplex.service"
    assert unit_path.exists()
    content = unit_path.read_text()
    assert "[Unit]" in content
    assert "[Service]" in content
    assert "[Install]" in content
    assert "muxplex" in content
    assert "default.target" in content


def test_install_service_system_mode_target(tmp_path, monkeypatch):
    """install_service(system=True) targets multi-user.target in the unit file."""
    from muxplex.cli import install_service

    # Redirect the system path to tmp so we don't write to /etc
    unit_path = tmp_path / "muxplex.service"
    monkeypatch.setattr("muxplex.cli._system_service_path", unit_path)

    install_service(system=True)

    assert unit_path.exists()
    content = unit_path.read_text()
    assert "multi-user.target" in content


def test_dunder_main_calls_main():
    """python -m muxplex must call cli.main()."""
    with patch("muxplex.cli.main") as mock_main:
        # Simulate `python -m muxplex` by exec'ing __main__.py
        import importlib
        import muxplex.__main__  # noqa: F401

        # The import itself calls main() at module level
        # Re-exec to test:
        mock_main.reset_mock()
        exec(Path("muxplex/__main__.py").read_text())
        mock_main.assert_called_once()
```

**Step 2: Run tests to verify they fail**

```bash
cd /home/bkrabach/dev/web-tmux/muxplex
python -m pytest muxplex/tests/test_cli.py -v 2>&1 | head -30
```
Expected: **FAIL** — `muxplex.cli` does not exist yet.

**Step 3: Create `muxplex/cli.py`**

```python
"""muxplex CLI — web-based tmux session dashboard."""

import argparse
import os
import sys
from pathlib import Path

# Module-level path constants (overridable in tests via monkeypatch)
_system_service_path = Path("/etc/systemd/system/muxplex.service")


def serve(host: str = "0.0.0.0", port: int = 8088) -> None:
    """Start the muxplex server."""
    import uvicorn  # noqa: PLC0415

    os.environ.setdefault("MUXPLEX_PORT", str(port))

    from muxplex.main import app  # noqa: PLC0415

    print(f"  muxplex → http://{host}:{port}")
    uvicorn.run(app, host=host, port=port, log_level="warning")


def install_service(*, system: bool = False) -> None:
    """Install muxplex as a systemd service."""
    executable = sys.executable

    unit = f"""\
[Unit]
Description=muxplex — web-based tmux session dashboard
After=network.target

[Service]
Type=simple
ExecStart={executable} -m muxplex
Restart=on-failure
RestartSec=5s
Environment=PATH={os.environ.get('PATH', '/usr/local/bin:/usr/bin:/bin')}

[Install]
WantedBy={"multi-user.target" if system else "default.target"}
"""

    if system:
        path = _system_service_path
        reload_cmd = "sudo systemctl daemon-reload && sudo systemctl enable --now muxplex"
    else:
        path = Path.home() / ".config" / "systemd" / "user" / "muxplex.service"
        path.parent.mkdir(parents=True, exist_ok=True)
        reload_cmd = "systemctl --user daemon-reload && systemctl --user enable --now muxplex"

    path.write_text(unit)
    print(f"Service file written to {path}")
    print(f"Enable with:\n  {reload_cmd}")


def main() -> None:
    """CLI entry point."""
    parser = argparse.ArgumentParser(
        prog="muxplex",
        description="muxplex — web-based tmux session dashboard",
    )
    parser.add_argument("--host", default="0.0.0.0", help="Bind host (default: 0.0.0.0)")
    parser.add_argument("--port", type=int, default=8088, help="Port (default: 8088)")

    sub = parser.add_subparsers(dest="command")
    sub.add_parser("serve", help="Start the server (default)")

    svc = sub.add_parser("install-service", help="Install systemd service unit")
    svc.add_argument("--system", action="store_true", help="System-wide (requires sudo)")

    args = parser.parse_args()

    if args.command == "install-service":
        install_service(system=args.system)
    else:
        serve(host=args.host, port=args.port)
```

**Step 4: Create `muxplex/__main__.py`**

```python
"""Allow running muxplex as: python -m muxplex"""

from muxplex.cli import main

main()
```

**Step 5: Run tests to verify pass**

```bash
cd /home/bkrabach/dev/web-tmux/muxplex
python -m pytest muxplex/tests/test_cli.py -v
```
Expected: **PASS** (all 8 tests)

Run full suite:
```bash
python -m pytest muxplex/tests/ --ignore=muxplex/tests/test_integration.py -q 2>&1 | tail -5
```
Expected: **178 passed** (170 + 8 new)

**Step 6: Commit**

```bash
git add -A && git commit -m "feat: add CLI entry point (muxplex serve, muxplex install-service) and __main__.py"
```

---

### Task 4: Update `pyproject.toml` for full distribution packaging

**Files:**
- Modify: `pyproject.toml` (complete rewrite)

**Step 1: No new tests needed**

The existing test suite implicitly validates the package is importable. The verification step below confirms `pip install -e .` and the entry point work.

**Step 2: Replace `pyproject.toml` contents entirely**

```toml
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "muxplex"
version = "0.1.0"
description = "Web-based tmux session dashboard — access all your tmux sessions from any browser"
readme = "README.md"
license = { text = "MIT" }
requires-python = ">=3.11"
dependencies = [
    "fastapi>=0.115.0",
    "uvicorn[standard]>=0.30.0",
    "aiofiles>=23.0",
    "websockets>=11.0",
]

[project.optional-dependencies]
dev = [
    "httpx>=0.27.0",
    "pytest>=8.0.0",
    "pytest-asyncio>=0.23.0",
    "beautifulsoup4>=4.12",
]

[project.scripts]
muxplex = "muxplex.cli:main"

[project.urls]
Repository = "https://github.com/bkrabach/muxplex"
Issues = "https://github.com/bkrabach/muxplex/issues"

[tool.hatch.build.targets.wheel]
packages = ["muxplex"]

[tool.pytest.ini_options]
testpaths = ["muxplex/tests"]
asyncio_mode = "auto"
addopts = "--import-mode=importlib -m 'not integration'"
markers = [
    "integration: marks tests as integration tests requiring real tmux (deselect with '-m not integration')",
]
```

**Step 3: Verify installability**

```bash
cd /home/bkrabach/dev/web-tmux/muxplex
pip install -e ".[dev]" --quiet
```

Then verify the entry point:
```bash
muxplex --help
```
Expected output should show:
```
usage: muxplex [-h] [--host HOST] [--port PORT] {serve,install-service} ...
```

Also verify `python -m muxplex --help` shows the same.

**Step 4: Run full test suite one more time**

```bash
cd /home/bkrabach/dev/web-tmux/muxplex
python -m pytest -q 2>&1 | tail -5
```
Expected: all tests pass.

**Step 5: Commit**

```bash
git add -A && git commit -m "chore: configure pyproject.toml for distribution (entry point, deps, hatchling build)"
```

---

### Task 5: Rewrite `README.md`

**Files:**
- Modify: `README.md`

**Step 1: No tests needed — doc-only change**

**Step 2: Replace `README.md` contents**

```markdown
# muxplex

> Web-based tmux session dashboard — access and manage all your tmux sessions from any browser or mobile device.

![muxplex dashboard](assets/branding/og/og-dark.png)

## Features

- Live grid of all running tmux sessions with snapshot previews
- Full interactive terminal in the browser (via ttyd + xterm.js)
- Collapsible session sidebar — switch sessions without leaving the terminal
- Bell / activity notifications
- Mobile-friendly responsive layout, PWA-capable
- Works over Tailscale / private network

## Prerequisites

- **tmux** — must be installed and running sessions
- **ttyd** — WebSocket bridge for terminal access (`brew install ttyd` / `apt install ttyd`)
- **Python 3.11+**

## Quick start (uvx — no install)

```bash
uvx --from git+https://github.com/bkrabach/muxplex muxplex
```

Open http://localhost:8088 in your browser.

## Install permanently

```bash
uv tool install git+https://github.com/bkrabach/muxplex
muxplex
```

## Install as a service (systemd)

```bash
# User service (no sudo required)
muxplex install-service
systemctl --user daemon-reload
systemctl --user enable --now muxplex

# System service (runs on boot for all users)
muxplex install-service --system
sudo systemctl daemon-reload
sudo systemctl enable --now muxplex
```

## Usage

```
muxplex [--host HOST] [--port PORT] [serve]
muxplex install-service [--system]
```

| Option | Default | Description |
|--------|---------|-------------|
| `--host` | `0.0.0.0` | Bind address |
| `--port` | `8088` | Port to serve on |
| `install-service` | — | Install systemd service unit |
| `--system` | false | System-wide service (requires sudo) |

## Development

```bash
git clone https://github.com/bkrabach/muxplex
cd muxplex
pip install -e ".[dev]"

# Run server
muxplex

# Run tests
python -m pytest
node --test muxplex/frontend/tests/test_app.mjs
node --test muxplex/frontend/tests/test_terminal.mjs
```

## Architecture

- **muxplex/** — Python package (FastAPI coordinator + CLI)
  - `main.py` — FastAPI app: session API, static frontend, WebSocket proxy to ttyd
  - `sessions.py` — tmux session enumeration and snapshot capture
  - `bells.py` — bell/activity detection
  - `ttyd.py` — ttyd process lifecycle management
  - `state.py` — persistent state management (JSON)
  - `cli.py` — CLI entry point (`muxplex serve`, `muxplex install-service`)
  - `frontend/` — static web app (HTML/CSS/JS + xterm.js)
- **assets/branding/** — SVG sources, rendered PNGs, design tokens
- **scripts/** — `render-brand-assets.py` — regenerate brand PNGs from SVGs

## Brand assets

Design language, color tokens, and brand assets in `assets/branding/`. Regenerate:

```bash
python scripts/render-brand-assets.py
```
```

**Step 3: Commit**

```bash
git add -A && git commit -m "docs: rewrite README with uvx/uv install instructions and full usage guide"
```

---

## Post-plan: Git repo setup (manual, not automated)

After all 5 tasks are complete, the parent session will:

1. Create the GitHub repo at `github.com/bkrabach/muxplex`
2. Push the muxplex directory contents to it
3. Convert the local `muxplex/` directory into a git submodule of the parent `web-tmux` repo

These steps are outside the scope of this coding plan.