Codex Monitor

01 / The task

Live stream of Codex sessions and tool activity

The goal was to observe Codex activity on a separate subdomain without affecting model requests. Monitoring must tolerate NATS outages, resume by cursor and separate owner-only sessions from explicitly published broadcasts.

Use case: The owner observes Codex work while visitors see only explicitly published read-only sessions.

Work done

• Added HTTP, SSE and WebSocket observation inside the Ruby proxy without changing the primary relay flow.
• Implemented sanitization, a bounded file outbox, a dedicated JetStream stream and a durable SQLite WAL projector.
• Extended the Vue interface with sessions, reasoning and tool timeline, traffic, usage, delivery health and comparison.
• Added manual chat titles, collapsible service context, publication preview, expiring links and immediate broadcast revocation.

03 / Technology

Stack

Shares use Git application-file bytes at pinned revisions. Each file belongs to one subsystem under scripts/generate-stack-share.mjs rules; tests, assets, dependencies and generated files are excluded. Rounded to 0.1%. This describes code composition, not proficiency.

04 / Decisions

How the project works

• The proxy copies sanitized events into a bounded outbox; NATS downtime does not stop a Codex request.
• The JetStream consumer acknowledges an event after a transactional projection write; eventId and sequence protect history from redelivery.
• Usage is stored per attempt and revision snapshot: cached counts within input, reasoning within output, and legacy aggregates remain separate.
• The default title comes from the first user message. A manual Codex Monitor title takes precedence and does not rename the chat in Codex.
• A public link contains only the permitted history of one selected session, lasts up to seven days and stops immediately on revocation.
• The earlier YouTrack/NATS worker remains a separate path and is not mixed with passive Codex monitoring.
• The monitor and YouTrack gateway use NATS directly. The Synadia Agents SDK, discovery and generic prompt bridge were removed; job and result queues are preserved.

05 / Verification

Demo workflows

1. Select a session, set a clear title and inspect the instruction, reasoning, messages and tools in chronological order.
2. Open Traffic and correlate request, attempt, transport, duration and sanitized event identifiers.
3. Review per-attempt usage and inspect proxy, NATS, projector, cursor and outbox state.
4. Review the permitted history range, publish a temporary link, open it as a visitor and revoke it immediately.

Check results

• In the live load snapshot, event delivery p50 was 128 ms and p95 was 172 ms; model response time is excluded.
• One validation session ledger increased by 272 tokens and retained the same total after a projector restart.
• During validation the outbox was empty, NATS had no pending or ackPending messages, and no OOM event was found.

Limitations

• Codex Gateway is the sole data source; local Codex Desktop and App Server files are not read.
• Encrypted reasoning is not reconstructed, hidden system/developer instructions are not stored, and no traffic only means no new events.
• Agent hierarchy appears only with explicit proxy identifiers; the system does not start, stop or reconfigure models.
• Automatic sanitization covers known secrets, while the owner still reviews the full preview before publishing.