Codex Monitor

About the project

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.

Codex Monitor displays real events copied by Codex Gateway from HTTP, SSE and WebSocket traffic. A non-blocking outbox publishes sanitized events to NATS JetStream, a projector stores the view in SQLite, and Bun/Vue exposes sessions, reasoning, tools, usage, errors and public broadcasts.

What sets the implementation apart

Events come from the real proxy rather than a UI simulator. eventId and sequence make projection idempotent, the durable consumer acknowledges after persistence, and usage is counted per attempt without re-adding snapshots. Temporary links can be revoked immediately; the older YouTrack flow remains a separate subsystem.

Application-code composition

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.

• 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.

Screenshots, diagrams and source evidence retain their original language; captions and descriptions are translated.

Architecture and diagrams

• 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.

Code map: files and dependencies

This map is tied to version 72fb980fa7d1. The table lists the screen or API, related module and data.

Using the code map

1. Before making a change, find the feature and trace its links to the API, state and storage.
2. Check inputs, errors, repeated events and dependent workflows.
3. After making a change, update the map and affected diagrams alongside the code.
4. Run the related checks and link the new evidence to the source version.

Workflows and API

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.

Verification of the published version

CI: Proxy monitoring checks ↗ · 9da19ee0 · historical run of a different version · 2026-09-07T22:55:40Z

CI: Native NATS / Codex Monitor checks ↗ · 72fb980f · this demo's version · 2026-09-08

• CI: Ruby observer tests, Bun projector tests, TypeScript checks and a production Vue build for SHA 9da19ee.
• Real SSE and WebSocket traffic, reasoning and responses, exact usage increments, refresh recovery and projector restart were verified on the VPS.
• Ten concurrent public WebSocket viewers received 100 updates; delivery p95 was 172 ms and revoking ten connections took 83 ms.
• Fragmented-secret sanitization, private-session isolation, safe Markdown/JSON text and desktop/mobile layouts without horizontal overflow were verified.

These checks apply to the listed version. Business metrics and model quality on an independent dataset were not measured.

Measurements

• 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.

Running and operating

Monitoring is enabled independently for permitted proxy users. Ordinary raw tracing remains disabled.

Text history is retained for 24 hours, the usage ledger for 90 days, the stream is limited to 1 GiB and the file outbox to 256 MiB.

Before a change, trace UI to API to SQLite projection to JetStream event to proxy observer, update the contract and verify redelivery.

Disable with MONITOR_ENABLED=false and proxy recreation; keep SQLite, JetStream and outbox data during rollback.

The current console is named Codex Monitor. /console/youtrack exposes gateway, NATS and queue status. Archived screenshots may show the previous UI. Upstream styling license notices remain in the repository.

Stack

Materials and source code

Codex Gateway integration and monitoring release: 7–8 September 2026.

The evidence archive retains its original language.