littleorgans/transport-matters

1. What this repo is

Transport Matters is a local control plane for agent traffic. It sits between a coding agent and its upstream provider, captures each turn, lets you inspect/edit the next outbound request, and persists artifacts for later replay and debugging.

2. Top-level shape

This is a three-part monorepo:

- api/: the Python backend, CLI, proxy orchestration, capture pipeline, and FastAPI control API

- www/: the React/Vite web UI that renders exchanges, session timelines, editors, and the canvas experience

- desktop/: an Electron shell that launches the backend and opens the UI as a desktop app

There is also a small shared/ folder for cross-cutting schema data.

3. Primary runtime path

The main operational flow is:

- user runs transport-matters claude, codex, or desktop

- the CLI starts a local backend and a proxy

- the managed agent process is configured to talk through that proxy

- upstream provider traffic is intercepted, parsed, optionally paused, edited, then forwarded

- captured results are stored locally and surfaced in the UI

4. Provider-specific transport boundary

The backend has distinct paths for:

- Claude Code: reverse proxy in front of api.anthropic.com, with ANTHROPIC_BASE_URL

- Codex: explicit HTTPS proxy for ChatGPT/Codex websocket traffic, with managed HTTPS_PROXY, HTTP_PROXY, and CODEX_CA_CERTIFICATE

These provider paths are not just config variants; they drive different parsing, serialization, and diagnostics logic under api/src/transport_matters/codex/ and api/src/transport_matters/adapters/.

5. Transport capture and curation pipeline

The transport layer converts raw provider requests into an internal request representation, applies deterministic curation rules, can stop at a breakpoint for manual editing, then serializes back to provider wire format. This is the architectural core of the repo: raw network traffic in, curated request back out, with both forms preserved.

6. Session, run, and artifact storage

Captures are organized per workspace and per run. The backend writes run-scoped artifacts under ~/.transport-matters/workspaces/{slug}/{hash}/{run_id}/..., including lock files, manifests, index.jsonl, exchange records, and proxy logs. This run isolation is important: multiple launches from the same working directory are intentionally supported without collisions.

7. Database-backed session state

The backend also uses a Postgres-backed session store, managed through api/migrations/ and the session/ package. Disk storage holds artifacts and logs; the database stores the structured session/index metadata used by the API and UI. The two storage layers are complementary rather than redundant.

8. FastAPI control plane

The api/src/transport_matters/api/v1/ package exposes the control API:

- session and run listing

- exchange retrieval and filtering

- breakpoint control

- runtime template and override management

- local file/resource content access

- streaming endpoints for live updates

The API is the read/write control surface for the UI and for CLI-driven orchestration.

9. Backend orchestration and process supervision

The backend has explicit process-management subsystems:

- run_manager, supervisor, shared_proxy, and pty_session manage child processes and attached terminals

- launch_* and runtime_* modules shape how a run is started and tracked

- shared_proxy/ coordinates detached backend instances and their process lifecycle

This is why the system can support detached desktop backends, live tails, and multiple concurrent runs in one workspace.

10. CLI as the operator entrypoint

The CLI package is a real subsystem, not a thin wrapper. It handles command dispatch, launch profiles, path resolution, port selection, health checks, trust setup, Codex/Claude-specific bootstrapping, and “doctor”/“tail”/“list”/“paths” operational commands. The CLI is the first boundary that decides whether the repo behaves like a proxy runner, a backend service, or a desktop launcher.

11. Web UI architecture

The www/ app is a client-side UI for inspecting and controlling captures. It is organized around:

- a session canvas with panes, docking, drag/drop, route switching, and persistence

- an exchange inspector for turn details and transport timelines

- breakpoint and override editors

- resource viewers for text, JSON, images, markdown, binary, and provider artifacts

The UI consumes backend APIs and live event streams; it does not own the authoritative session state.

12. Live data flow into the UI

The UI has a stream-oriented path from backend to frontend:

- session events and exchange updates are received via streaming hooks

- reducers/store modules normalize those events into UI state

- panes render from that state, while persistence modules remember layout and user choices

This streaming model is central for “live run” inspection and for the canvas/terminal views.

13. Desktop shell boundary

desktop/ packages the experience as Electron:

- main process launches or connects to the backend

- preload bridges expose a controlled API to the renderer

- renderer hosts the web app surface

The desktop shell is mostly about process lifecycle, backend health detection, and window management; the actual product logic still lives in api/ and www/.

14. Shared contracts and test fixtures

The repo relies heavily on explicit contracts and fixtures:

- JSON spec files in shared/

- provider transcripts and rollout fixtures in api/tests/fixtures/

- extensive tests for transport parsing, storage, UI reducers, and desktop integration

These fixtures are part of the architecture because they encode provider wire formats and replay scenarios the system must preserve exactly.

15. External dependencies that matter

The important external systems are:

- Anthropic API for Claude Code traffic

- ChatGPT/Codex websocket backend for Codex traffic

- Postgres for the session store

- mitmproxy for interception and explicit proxying

- Electron for the desktop wrapper

The design deliberately avoids system-wide proxy or certificate installation by keeping trust and proxy scope process-local.