{"id":49074673,"url":"https://github.com/gastonmorixe/codex-xrays","last_synced_at":"2026-04-20T09:34:08.989Z","repository":{"id":312010832,"uuid":"1045950595","full_name":"gastonmorixe/codex-xrays","owner":"gastonmorixe","description":"🛟 A fast, colorful TUI to visualize streaming Codex logs in real time","archived":false,"fork":false,"pushed_at":"2025-09-11T22:17:18.000Z","size":58,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-12T00:58:11.008Z","etag":null,"topics":["agents","cli","codex","curses","developer-tools","logs","openai","streaming","tui","visualization"],"latest_commit_sha":null,"homepage":"http://github.com/openai/codex","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gastonmorixe.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-28T00:55:02.000Z","updated_at":"2025-08-28T15:12:54.000Z","dependencies_parsed_at":"2025-08-28T08:55:03.947Z","dependency_job_id":"778357e2-0755-45f3-acda-620152c686a9","html_url":"https://github.com/gastonmorixe/codex-xrays","commit_stats":null,"previous_names":["gastonmorixe/codex-xrays"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/gastonmorixe/codex-xrays","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gastonmorixe%2Fcodex-xrays","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gastonmorixe%2Fcodex-xrays/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gastonmorixe%2Fcodex-xrays/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gastonmorixe%2Fcodex-xrays/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gastonmorixe","download_url":"https://codeload.github.com/gastonmorixe/codex-xrays/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gastonmorixe%2Fcodex-xrays/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32041552,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-20T00:18:06.643Z","status":"online","status_checked_at":"2026-04-20T02:00:06.527Z","response_time":94,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","cli","codex","curses","developer-tools","logs","openai","streaming","tui","visualization"],"created_at":"2026-04-20T09:34:08.189Z","updated_at":"2026-04-20T09:34:08.971Z","avatar_url":"https://github.com/gastonmorixe.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🛟 CodeXRays 1.0.1\n\n\u003cp\u003e\u003ca href=\"https://www.youtube.com/watch?v=SEFqOdGIFE4\" target=\"_blank\" title=\"Youtube - CodeXRay - OpenAI Codex CLI real-time interactive logs visualizer\"\u003e\u003cimg width=\"1046\" height=\"638\" alt=\"image\" src=\"https://github.com/user-attachments/assets/4ce3cea3-7638-408b-9433-d6714d30ddd4\" /\u003e\u003c/a\u003e\u003c/p\u003e\n\n**🛟 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.\n\n## 🚀 Quick Start\n\n```bash\n# 🧠 Pretty list previews + 🎨 JSON detail view (full screen)\n# tails ~/.codex/log/codex-tui.log by default\n$ pipx run --spec git+https://github.com/gastonmorixe/codex-xrays \\\n    codex-xrays --pretty-preview --pretty-mode hybrid --json-pretty\n```\n\n```bash\n# Add the following RUST_LOG env var so codex\n# saves detailed log ~/.codex/log/codex-tui.log\n\n$ RUST_LOG=codex_core=trace,codex_exec=debug,codex_mcp_client=debug \\\n   codex -m gpt-5\n```\n\n## Examples\n\nPlan tool vs raw plan log\n\n\u003cimg width=\"1138\" height=\"696\" alt=\"Plan tool vs raw plan log\" src=\"https://github.com/user-attachments/assets/80ea4aee-f0cd-433f-8abc-6fff453ae46b\" /\u003e\n\nWorking in real time\n\n\u003cimg width=\"1545\" height=\"940\" alt=\"Screenshot 2025-08-28 at 00 41 34\" src=\"https://github.com/user-attachments/assets/dcb1a029-b6bf-4033-85da-dd52abbdf1b0\" /\u003e\n\n## Highlights\n\n- Real‑time tailing of `codex-tui.log` with log‑rotation detection.\n- Delta aggregation per `(item_id, output_index)`; renders colorized, multiline entries.\n- Selection with arrow keys, full‑screen detail view, and live updates.\n- Pin items to the top, filter by event type, and export selected content to a file.\n- Shows recent non‑SSE lines for additional context (INFO/WARN/ERROR badges).\n- Memory‑safe rolling buffers and high‑frequency rendering loop tuned for fast streams.\n\n## 🚀 Getting Started\n\n- Requirements: Python 3.8+.\n  - macOS/Linux: comes with `curses`.\n  - Windows: `pip install windows-curses`.\n\n- Install (pipx):\n\n```bash\n# Install once\npipx install git+https://github.com/gastonmorixe/codex-xrays\n\n# Recommended run (best experience):\n# 🧠 Pretty list previews + 🎨 JSON detail view (full screen)\n# tails ~/.codex/log/codex-tui.log by default\ncodex-xrays --pretty-preview --pretty-mode hybrid --json-pretty\n```\n\n- From the repo/log directory (without install):\n\n```bash\n# Same, without pipx\npython3 codexrays.py --pretty-preview --pretty-mode hybrid --json-pretty\n# Extras\npython3 codexrays.py --from-start\npython3 codexrays.py -f ./codex-tui.log -L 8 --max-items 300\n# Or via env var (auto-on pretty)\nXRAYS_PRETTY=1 XRAYS_PRETTY_MODE=hybrid python3 codexrays.py --json-pretty\n```\n\n## ⌨️ Keybindings (at a glance)\n\n- q: quit • ↑/↓ or j/k: move • Enter: full‑screen detail\n- x: pin/unpin • f: filter (all → args.delta → output.delta → error → all)\n- e: export selection → `codexrays_export_*.txt`\n- b: pretty preview mode (off → summary → hybrid)\n- m: more lines for selected item (`--lines-expanded`)\n- T: jump to newest and resume follow (banner shows “(X) newer logs — press T to follow”)\n- p: pause • s: toggle “from start” • Space: refresh\n- Full‑screen JSON (`--json-pretty`): w toggles word‑wrap (🟢 on by default)\n\n## ⚙️ Command‑line Options\n\n- `-f, --file \u003cpath\u003e`: Path to the log file. Default: `~/.codex/log/codex-tui.log`.\n- `--from-start`: Read from the start of the file (otherwise tail from end).\n- `--max-items \u003cN\u003e`: Max distinct `(item_id, output_index)` streams to keep in memory. Default: 200.\n- `-L, --lines-per-item \u003cN\u003e`: Maximum wrapped lines to render per entry in list view. Default: 5.\n- `--lines-expanded \u003cN\u003e`: Lines to show when an item is expanded with `m`. Default: 12.\n- `--pretty-preview`: Enable emoji + parsed previews (can also set `XRAYS_PRETTY=1`).\n- `--pretty-mode \u003csummary|hybrid\u003e`: Summary only, or summary plus a raw excerpt beneath.\n- `--keep-ansi`: Do not strip ANSI color codes from recent logs (default strips them).\n- `--json-pretty`: In full‑screen detail view, pretty‑print JSON and color keys/values.\n\n## 🖼️ What the UI Shows\n\n- Header: app name + `[FOLLOWING]` badge when active, plus counters (🧮 events/deltas, ⚡ EPS), total items, active filter, and `pretty:off|summary|hybrid`.\n- 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.\n- Recent logs: compact tail of non‑delta events. With pretty mode, SSE/FunctionCall lines are summarized (🧰 tools, 🔎 queries, 🔗 hosts, 📄 files, 🛠️ commands, 💬 text).\n\n## 🛠️ Configuration\n\n- `XRAYS_PRETTY=1`: Start with pretty previews enabled (same as `--pretty-preview`).\n- `XRAYS_PRETTY_MODE=summary|hybrid`: Choose preview style when enabled.\n- `XRAYS_KEEP_ANSI=1`: Keep ANSI color codes in recent logs (by default they are stripped).\n\n## 🔎 Parsing Logic\n\n- Lines matching `... SSE event: {json}` are parsed as JSON.\n- If `type` ends with `.delta` and has `item_id`, the `delta` string is appended to that stream, keyed by `(item_id, output_index)`.\n- Non‑delta SSE lines and all other non‑SSE log lines are kept in a small “Recent logs” buffer.\n- Event type coloring:\n  - `response.function_call_arguments.delta`: cyan\n  - `response.output_text.delta`: green\n  - Tool/function call related types: magenta\n  - Types containing `error`: red\n  - Others: default\n\n## 🧵 Multiline Rendering\n\n- Each entry renders up to `--lines-per-item` wrapped lines.\n- In normal mode, shows the most recent lines; in pretty mode, shows the summary first (and, in `hybrid`, a raw excerpt beneath).\n- Wrapping is character‑based to ensure speed and deterministic layout.\n- The selection auto‑scrolls to remain visible as new events push items.\n\n## Full‑screen Detail View\n\n- Press Enter on a selected entry to open a full‑screen viewer.\n- Scroll with ↑/↓/PgUp/PgDn/Home/End. Live updates continue while viewing.\n- Use `e` to export the full content; `x` to pin/unpin; `q` or ESC to return.\n\n## Export\n\n- `e` writes the selected item’s content to `codexrays_export_\u003cid\u003e_\u003cidx\u003e_\u003ctimestamp\u003e.txt` in the current directory.\n\n## Performance Notes\n\n- File tailing uses non‑blocking reads with reopen on rotation/truncation.\n- Each stream keeps a rolling window (character budget) to bound memory.\n- The UI loop targets ~50 FPS; EPS is sampled every 0.5 seconds.\n\n## Troubleshooting\n\n## Preview Behavior\n\n- 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.\n- Recent logs strip ANSI color codes by default for readability; use `--keep-ansi` if your logs rely on terminal colors.\n- Full‑screen JSON (with `--json-pretty`) pretty‑prints objects/arrays with light colors; press `w` to wrap/unwrap long values.\n- No colors: ensure your terminal supports ANSI colors; `TERM` should be something like `xterm-256color`.\n- Windows: install `windows-curses` (`pip install windows-curses`). Run from a Unicode‑capable terminal.\n- Large files: prefer tail mode (default). Use `--from-start` only when needed.\n- Log path: pass `-f /path/to/codex-tui.log` if not running in the log folder.\n- Flicker: prefer a modern terminal and a reasonable window size; the app uses full‑screen redraws for speed.\n\n## Currently Implemented\n\n- Real‑time tail with rotation detection\n- Delta aggregation per `(item_id, output_index)`\n- Multiline wrapped rendering with per‑entry cap (`-L`)\n- Selection + full‑screen detail view with live updates\n- Pin/unpin entries\n- Type filters (all/args/output/error)\n- Export selected content\n- Recent non‑SSE logs panel with level badges\n- Stats header: events, deltas, EPS, items, filter\n\n## Roadmap / Ideas\n\n- Search: `/` to search within the full‑screen view and list; `n/N` to jump.\n- Copy to clipboard: `y` yank current selection (platform‑aware backends).\n- Rich JSON rendering: pretty‑print structured payloads with syntax highlighting.\n- Sequence integrity: visualize gaps or out‑of‑order `sequence_number` with badges.\n- Grouping and tabs: group entries by session/run; tabbed views per group.\n- Saved views \u0026 filters: persist pins and filters across runs.\n- Alerting: simple rules to badge or beep on matches (e.g., errors, keywords).\n- Theming: light/dark themes and custom color pairs.\n- Input sources: follow multiple files, named pipes, or sockets; merge streams.\n- Export bundles: save a session (pins + selected entries + metadata) to a folder.\n- Web/remote view: optional headless server + web UI mirroring the TUI.\n\n### UX \u0026 Interaction\n\n- Per‑item pretty toggle: expand only the selected item’s preview (`B`).\n- Detail view prettify: optional parsed rendering in the fullscreen view (`D`).\n- Multi‑file run: `--files a.log b.log` with per‑file badges and filters.\n\n### Preview \u0026 Parsing\n\n- Tool taxonomy: map common tools to friendly names and surface relevant knobs (e.g., `top_k`, `temperature`).\n- Redaction: detect and mask secrets (API keys, Bearer tokens, high‑entropy strings) in previews.\n\n### Performance \u0026 Robustness\n\n- Word‑boundary wrapping: `--wrap word` to reduce chopped words.\n- Smarter redraws: diff rows and use `noutrefresh()/doupdate()` to lower CPU.\n- Backpressure: reduce render rate at very high EPS or small terminals.\n\n### Configuration \u0026 Packaging\n\n- Export names: switch to `xrays_export_*.txt` and ignore in VCS.\n- Defaults file: support `~/.xrays.toml` for persistent flags (pretty mode, lines per item).\n- No‑color mode: `--no-color` for dumb terminals and CI outputs.\n- Packaging: add `pyproject.toml` + entry point (`codex-xrays`) for `pipx` install.\n\n## Contributing\n\n- Issues and PRs welcome. Keep changes focused, avoid unrelated refactors.\n- Style: small, focused functions; prefer predictable redraw over cleverness.\n- Please test with a large/fast log stream before submitting.\n\n## License\n\nGaston Morixe - MIT License 2025\n\n## Release\n\n- Update `CHANGELOG.md` with a new `## \u003cversion\u003e` section.\n- Tag the version: `git tag -a 1.0.1 -m \"CodeXRays 1.0.1\" \u0026\u0026 git push origin 1.0.1`.\n- GitHub Actions publishes a release using the matching CHANGELOG section (falls back to commits if not found).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgastonmorixe%2Fcodex-xrays","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgastonmorixe%2Fcodex-xrays","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgastonmorixe%2Fcodex-xrays/lists"}