fix(cli): strip OpenRTC flags; align subcommands with LiveKit Agents CLI

.agents/skills/openrtc-python/SKILL.md

@@ -111,12 +111,20 @@ exactly one `Agent` subclass at module scope, and the filename doesn't start
 with `_`. Fix and re-run `openrtc list` until all agents appear.
 
 ```bash
-# Development mode (auto-reload)
+# Development mode (auto-reload) — set LIVEKIT_* env vars first
 openrtc dev --agents-dir ./agents
 
 # Production mode
 openrtc start --agents-dir ./agents
 
+# Same LiveKit subcommands as python agent.py: console, connect, download-files
+# openrtc console --agents-dir ./agents
+# openrtc connect --agents-dir ./agents --room my-room
+
+# Optional: JSON Lines metrics + sidecar TUI (pip install 'openrtc[cli,tui]')
+# openrtc dev --agents-dir ./agents --metrics-jsonl ./metrics.jsonl
+# openrtc tui --watch ./metrics.jsonl
+
 # Or run the entrypoint directly
 python main.py dev
 ```
@@ -144,6 +152,10 @@ Unknown metadata names raise `ValueError` — no silent fallback.
 - **`pool.run()` delegates to `livekit.agents.cli.run_app()`.** The first CLI
   argument must be `dev` or `start` (e.g. `python main.py dev`). Without it,
   the process exits immediately with a usage error.
+- **`openrtc dev|start|…` sets up discovery then calls the same LiveKit CLI.**
+  OpenRTC-only flags (`--agents-dir`, `--dashboard`, `--metrics-jsonl`, …) are
+  stripped from `sys.argv` before LiveKit parses arguments—do not expect LiveKit
+  to understand them.
 - **Provider objects must be pickleable.** OpenRTC has built-in serialization
   for `livekit.plugins.openai` STT, TTS, and LLM. Other providers: use string
   identifiers or ensure the object is natively pickleable.

.github/workflows/test.yml

@@ -26,7 +26,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          python -m pip install -e ".[cli]" pytest pytest-asyncio pytest-cov
+          python -m pip install -e ".[cli,tui]" pytest pytest-asyncio pytest-cov
 
       - name: Run tests with coverage
         run: pytest --cov=openrtc --cov-report=xml --cov-fail-under=80

.gitignore

@@ -164,6 +164,9 @@ venv.bak/
 # Rope project settings
 .ropeproject
 
+# Node (VitePress docs)
+node_modules/
+
 # mkdocs documentation
 /site
 

AGENTS.md

@@ -403,7 +403,7 @@ When in doubt:
 All commands are documented in `CONTRIBUTING.md`. Quick reference:
 
 - **Install deps:** `uv sync --group dev`
-- **Tests:** `uv run pytest` (36 tests, all self-contained)
+- **Tests:** `uv run pytest` (self-contained; no LiveKit server required)
 - **Lint:** `uv run ruff check .`
 - **Format check:** `uv run ruff format --check .`
 - **Type check:** `uv run mypy src/` (3 pre-existing errors as of this writing)
@@ -414,6 +414,6 @@ All commands are documented in `CONTRIBUTING.md`. Quick reference:
 - The `tests/conftest.py` creates a fake `livekit.agents` module when the real one isn't importable. This allows tests to run without the full LiveKit SDK. The real SDK *is* installed by `uv sync`, but if you see import weirdness in tests, this shim is the reason.
 - Version is derived from git tags via `hatch-vcs`. In a dev checkout the version will be something like `0.0.9.dev0+g<hash>`.
 - `mypy` has 3 pre-existing errors in `pool.py` — these are not regressions from your changes.
-- Running `openrtc start` or `openrtc dev` requires a running LiveKit server and provider API keys. For development validation, use `openrtc list` which exercises discovery and routing without network dependencies.
+- Running `openrtc start` or `openrtc dev` requires a running LiveKit server and provider API keys. For development validation, use `openrtc list` which exercises discovery and routing without network dependencies. The optional sidecar metrics TUI (`openrtc tui --watch`, requires `openrtc[tui]` / dev deps) tails `--metrics-jsonl` from a worker in another terminal.
 - `pytest-cov` is in the dev dependency group; CI uses `--cov-fail-under=80`; run
   `uv run pytest --cov=openrtc --cov-report=xml --cov-fail-under=80` to match.

CONTRIBUTING.md

@@ -15,8 +15,10 @@ This repository uses `uv` for local development.
 uv sync --group dev
 ```
 
-The dev group includes Typer and Rich so `uv run openrtc …` works without
-`--extra cli`. End users install the CLI with `pip install 'openrtc[cli]'`.
+The dev group includes Typer, Rich, and Textual so `uv run openrtc …` and
+`uv run openrtc tui …` work without extra install flags. End users install the
+CLI with `pip install 'openrtc[cli]'` and the sidecar TUI with
+`pip install 'openrtc[tui]'` (or `openrtc[cli,tui]` together).
 
 If you prefer, you can also install the package and dev dependencies with pip,
 but `uv` is the preferred workflow for contributors.