Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/gastonmorixe/codex-xrays

🛟 A fast, colorful TUI to visualize streaming Codex logs in real time
https://github.com/gastonmorixe/codex-xrays

agents cli codex curses developer-tools logs openai streaming tui visualization

Last synced: 3 months ago
JSON representation

🛟 A fast, colorful TUI to visualize streaming Codex logs in real time

Awesome Lists containing this project

README 

          
# 🛟 CodeXRays 1.0.1



image



**🛟 CodeXRays** — a friendly, fast TUI that shines a light on what [Codex](http://github.com/openai/codex) sessions are doing. It tails your live logs from OpenAI's [Codex](http://github.com/openai/codex), understands the streaming events, and presents them as a clean, colorful timeline with smart previews and a beautiful JSON detail view.



## 🚀 Quick Start



```bash

# 🧠 Pretty list previews + 🎨 JSON detail view (full screen)

# tails ~/.codex/log/codex-tui.log by default

$ pipx run --spec git+https://github.com/gastonmorixe/codex-xrays \

    codex-xrays --pretty-preview --pretty-mode hybrid --json-pretty

```



```bash

# Add the following RUST_LOG env var so codex

# saves detailed log ~/.codex/log/codex-tui.log



$ RUST_LOG=codex_core=trace,codex_exec=debug,codex_mcp_client=debug \

   codex -m gpt-5

```



## Examples



Plan tool vs raw plan log



Plan tool vs raw plan log



Working in real time



Screenshot 2025-08-28 at 00 41 34



## Highlights



- Real‑time tailing of `codex-tui.log` with log‑rotation detection.

- Delta aggregation per `(item_id, output_index)`; renders colorized, multiline entries.

- Selection with arrow keys, full‑screen detail view, and live updates.

- Pin items to the top, filter by event type, and export selected content to a file.

- Shows recent non‑SSE lines for additional context (INFO/WARN/ERROR badges).

- Memory‑safe rolling buffers and high‑frequency rendering loop tuned for fast streams.



## 🚀 Getting Started



- Requirements: Python 3.8+.

  - macOS/Linux: comes with `curses`.

  - Windows: `pip install windows-curses`.



- Install (pipx):



```bash

# Install once

pipx install git+https://github.com/gastonmorixe/codex-xrays



# Recommended run (best experience):

# 🧠 Pretty list previews + 🎨 JSON detail view (full screen)

# tails ~/.codex/log/codex-tui.log by default

codex-xrays --pretty-preview --pretty-mode hybrid --json-pretty

```



- From the repo/log directory (without install):



```bash

# Same, without pipx

python3 codexrays.py --pretty-preview --pretty-mode hybrid --json-pretty

# Extras

python3 codexrays.py --from-start

python3 codexrays.py -f ./codex-tui.log -L 8 --max-items 300

# Or via env var (auto-on pretty)

XRAYS_PRETTY=1 XRAYS_PRETTY_MODE=hybrid python3 codexrays.py --json-pretty

```



## ⌨️ Keybindings (at a glance)



- q: quit • ↑/↓ or j/k: move • Enter: full‑screen detail

- x: pin/unpin • f: filter (all → args.delta → output.delta → error → all)

- e: export selection → `codexrays_export_*.txt`

- b: pretty preview mode (off → summary → hybrid)

- m: more lines for selected item (`--lines-expanded`)

- T: jump to newest and resume follow (banner shows “(X) newer logs — press T to follow”)

- p: pause • s: toggle “from start” • Space: refresh

- Full‑screen JSON (`--json-pretty`): w toggles word‑wrap (🟢 on by default)



## ⚙️ Command‑line Options



- `-f, --file `: Path to the log file. Default: `~/.codex/log/codex-tui.log`.

- `--from-start`: Read from the start of the file (otherwise tail from end).

- `--max-items `: Max distinct `(item_id, output_index)` streams to keep in memory. Default: 200.

- `-L, --lines-per-item `: Maximum wrapped lines to render per entry in list view. Default: 5.

- `--lines-expanded `: Lines to show when an item is expanded with `m`. Default: 12.

- `--pretty-preview`: Enable emoji + parsed previews (can also set `XRAYS_PRETTY=1`).

- `--pretty-mode `: Summary only, or summary plus a raw excerpt beneath.

- `--keep-ansi`: Do not strip ANSI color codes from recent logs (default strips them).

- `--json-pretty`: In full‑screen detail view, pretty‑print JSON and color keys/values.



## 🖼️ What the UI Shows



- Header: app name + `[FOLLOWING]` badge when active, plus counters (🧮 events/deltas, ⚡ EPS), total items, active filter, and `pretty:off|summary|hybrid`.

- Main list: most recently updated entries first. Each entry shows `short_item_id#output_index:` plus up to `N` wrapped lines of the latest content. Colors map to event types.

- Recent logs: compact tail of non‑delta events. With pretty mode, SSE/FunctionCall lines are summarized (🧰 tools, 🔎 queries, 🔗 hosts, 📄 files, 🛠️ commands, 💬 text).



## 🛠️ Configuration



- `XRAYS_PRETTY=1`: Start with pretty previews enabled (same as `--pretty-preview`).

- `XRAYS_PRETTY_MODE=summary|hybrid`: Choose preview style when enabled.

- `XRAYS_KEEP_ANSI=1`: Keep ANSI color codes in recent logs (by default they are stripped).



## 🔎 Parsing Logic



- Lines matching `... SSE event: {json}` are parsed as JSON.

- If `type` ends with `.delta` and has `item_id`, the `delta` string is appended to that stream, keyed by `(item_id, output_index)`.

- Non‑delta SSE lines and all other non‑SSE log lines are kept in a small “Recent logs” buffer.

- Event type coloring:

  - `response.function_call_arguments.delta`: cyan

  - `response.output_text.delta`: green

  - Tool/function call related types: magenta

  - Types containing `error`: red

  - Others: default



## 🧵 Multiline Rendering



- Each entry renders up to `--lines-per-item` wrapped lines.

- In normal mode, shows the most recent lines; in pretty mode, shows the summary first (and, in `hybrid`, a raw excerpt beneath).

- Wrapping is character‑based to ensure speed and deterministic layout.

- The selection auto‑scrolls to remain visible as new events push items.



## Full‑screen Detail View



- Press Enter on a selected entry to open a full‑screen viewer.

- Scroll with ↑/↓/PgUp/PgDn/Home/End. Live updates continue while viewing.

- Use `e` to export the full content; `x` to pin/unpin; `q` or ESC to return.



## Export



- `e` writes the selected item’s content to `codexrays_export___.txt` in the current directory.



## Performance Notes



- File tailing uses non‑blocking reads with reopen on rotation/truncation.

- Each stream keeps a rolling window (character budget) to bound memory.

- The UI loop targets ~50 FPS; EPS is sampled every 0.5 seconds.



## Troubleshooting



## Preview Behavior



- Pretty mode shows a one-line summary followed by live tail lines, so the newest text is always visible. Increase `-L` or press `m` to see more.

- Recent logs strip ANSI color codes by default for readability; use `--keep-ansi` if your logs rely on terminal colors.

- Full‑screen JSON (with `--json-pretty`) pretty‑prints objects/arrays with light colors; press `w` to wrap/unwrap long values.

- No colors: ensure your terminal supports ANSI colors; `TERM` should be something like `xterm-256color`.

- Windows: install `windows-curses` (`pip install windows-curses`). Run from a Unicode‑capable terminal.

- Large files: prefer tail mode (default). Use `--from-start` only when needed.

- Log path: pass `-f /path/to/codex-tui.log` if not running in the log folder.

- Flicker: prefer a modern terminal and a reasonable window size; the app uses full‑screen redraws for speed.



## Currently Implemented



- Real‑time tail with rotation detection

- Delta aggregation per `(item_id, output_index)`

- Multiline wrapped rendering with per‑entry cap (`-L`)

- Selection + full‑screen detail view with live updates

- Pin/unpin entries

- Type filters (all/args/output/error)

- Export selected content

- Recent non‑SSE logs panel with level badges

- Stats header: events, deltas, EPS, items, filter



## Roadmap / Ideas



- Search: `/` to search within the full‑screen view and list; `n/N` to jump.

- Copy to clipboard: `y` yank current selection (platform‑aware backends).

- Rich JSON rendering: pretty‑print structured payloads with syntax highlighting.

- Sequence integrity: visualize gaps or out‑of‑order `sequence_number` with badges.

- Grouping and tabs: group entries by session/run; tabbed views per group.

- Saved views & filters: persist pins and filters across runs.

- Alerting: simple rules to badge or beep on matches (e.g., errors, keywords).

- Theming: light/dark themes and custom color pairs.

- Input sources: follow multiple files, named pipes, or sockets; merge streams.

- Export bundles: save a session (pins + selected entries + metadata) to a folder.

- Web/remote view: optional headless server + web UI mirroring the TUI.



### UX & Interaction



- Per‑item pretty toggle: expand only the selected item’s preview (`B`).

- Detail view prettify: optional parsed rendering in the fullscreen view (`D`).

- Multi‑file run: `--files a.log b.log` with per‑file badges and filters.



### Preview & Parsing



- Tool taxonomy: map common tools to friendly names and surface relevant knobs (e.g., `top_k`, `temperature`).

- Redaction: detect and mask secrets (API keys, Bearer tokens, high‑entropy strings) in previews.



### Performance & Robustness



- Word‑boundary wrapping: `--wrap word` to reduce chopped words.

- Smarter redraws: diff rows and use `noutrefresh()/doupdate()` to lower CPU.

- Backpressure: reduce render rate at very high EPS or small terminals.



### Configuration & Packaging



- Export names: switch to `xrays_export_*.txt` and ignore in VCS.

- Defaults file: support `~/.xrays.toml` for persistent flags (pretty mode, lines per item).

- No‑color mode: `--no-color` for dumb terminals and CI outputs.

- Packaging: add `pyproject.toml` + entry point (`codex-xrays`) for `pipx` install.



## Contributing



- Issues and PRs welcome. Keep changes focused, avoid unrelated refactors.

- Style: small, focused functions; prefer predictable redraw over cleverness.

- Please test with a large/fast log stream before submitting.



## License



Gaston Morixe - MIT License 2025



## Release



- Update `CHANGELOG.md` with a new `## ` section.

- Tag the version: `git tag -a 1.0.1 -m "CodeXRays 1.0.1" && git push origin 1.0.1`.

- GitHub Actions publishes a release using the matching CHANGELOG section (falls back to commits if not found).