Collector: Mux (coder/mux)

[willwashburn]

Target

Mux — Coder's multi-agent orchestrator (github.com/coder/mux).

Data

• Path: ~/.mux/sessions/<workspaceId>/session-usage.json
• Format: JSON with a byModel dict of aggregated token buckets per model
• Auth: Passive read only

References

• tokscale: crates/tokscale-core/src/sessions/mux.rs (314 lines) — the reference implementation.

Coverage

• Workspace ID: yes (becomes session ID)
• Model: yes (keys of byModel)
• Usage: per-model per-session aggregates only — one record per model per workspace, NOT per API call
• Cache: yes (nested under byModel[model].tokens)
• Cost: yes (nested cost_usd)
• Timestamp: lastRequest.timestamp if present, file mtime fallback

Gotchas

• Lowest granularity of any collector we've catalogued. Mux only writes per-model-per-session totals. No per-message, no per-turn, no per-tool-call data. burn waste (burn waste: per-tool-call and per-file spend attribution #3) and per-tool-call attribution will return empty for Mux sessions — surface a clear "this source lacks the granularity" note rather than empty tables.
• No tool-call content. Mux collects output without preserving the turn-by-turn decisions.
• Workspace ≠ session semantics. Mux's workspaceId is the orchestration unit, which may encompass multiple conceptual sessions. Map to TurnRecord.sessionId but document that one sessionId may cover many logical user interactions.
• Aggregation timestamps are lossy. Since usage is pre-aggregated, there's no per-hour or per-day breakdown available — burn summary --since 7d can't slice Mux data finer than the session-level mtime.

Work

• Implement packages/reader/src/mux.ts emitting TurnRecord with source: 'mux'. Emit one TurnRecord per byModel entry, with turnIndex: 0 and a note that granularity is aggregate.
• Add TurnRecord.granularity?: 'per-message' | 'per-session-aggregate' so downstream consumers (burn waste, burn claude-md) can skip aggregate-only data with a useful message rather than silently producing misleading output.
• Fixtures under tests/fixtures/mux/.
• Wire into ingest walker.

Priority

Low. Mux adoption is niche. The granularity limitation makes the data mostly useful for total-spend summaries, not the diagnostic work burn targets.