tail-codex

Two small CLIs for working with Codex session rollouts (rollout-*.jsonl):

1. codex-tail: render a session log in the same human style as codex exec (labels like thinking, codex, exec, tool output truncation, optional ANSI colors).
2. tail-codex-acp: follow a session log and emit an ACP session/update notification stream (JSON-RPC) suitable for visualizers.

This repo intentionally reuses the behavior of:

• OpenAI Codex CLI human output (codex-rs/exec/src/event_processor_with_human_output.rs)
• Zed Industries codex-acp replay logic (src/thread.rs replay history)

Install (editable)

cd /home/tools/tail-codex
python -m pip install -e .

Run via uv (no install)

cd /home/tools/tail-codex
uv run codex-tail -f -n 0 019c3bfa-43fd-78f0-ab40-758a1280a0a8
uv run tail-codex-acp -f --history 50 019c3bfa-43fd-78f0-ab40-758a1280a0a8

codex-tail

codex-tail --help

# Tail last 10 records (default) and exit
codex-tail 019c3bfa-43fd-78f0-ab40-758a1280a0a8

# By explicit path
codex-tail /root/.codex/sessions/2026/02/08/rollout-2026-02-08T09-39-43-019c3bfa-43fd-78f0-ab40-758a1280a0a8.jsonl

# By URL
codex-tail https://example.com/rollout-2026-02-08T09-39-43-019c3bfa-43fd-78f0-ab40-758a1280a0a8.jsonl

# By filename/content substring (best-effort)
codex-tail rollout-2026-02-08

# Follow like `tail -f` (show last 10, then stream new records)
codex-tail -f 019c3bfa-43fd-78f0-ab40-758a1280a0a8

# Follow like `tail -f` (only new records)
codex-tail -f -n 0 019c3bfa-43fd-78f0-ab40-758a1280a0a8

# Show last 200 records and then follow
codex-tail -f -n 200 019c3bfa-43fd-78f0-ab40-758a1280a0a8

# Reopen-by-name follow mode (handles rotation/replacement)
codex-tail --follow=name -n 0 019c3bfa-43fd-78f0-ab40-758a1280a0a8

# Replay from start (tail -n +1) and follow
codex-tail -f -n +1 019c3bfa-43fd-78f0-ab40-758a1280a0a8

# Compatibility: you can also use `--from start`
codex-tail --from start --no-follow 019c3bfa-43fd-78f0-ab40-758a1280a0a8

# One-shot live inject a user message into a running VS Code Codex session.
# Note: this requires the session to be active on the same machine (it finds the
# `codex app-server` process and writes to its stdin peer).
codex-tail --inject-only -m "Stop. New instructions: ..." 019c3bfa-43fd-78f0-ab40-758a1280a0a8

# Inject and then follow new records (tail -f style).
codex-tail -f -n 0 -m "Stop. New instructions: ..." 019c3bfa-43fd-78f0-ab40-758a1280a0a8

# If you want to inject without interrupting the current turn:
codex-tail --inject-only --no-interrupt -m "..." 019c3bfa-43fd-78f0-ab40-758a1280a0a8

# If you see `live inject warning: app-server stdin recv-q increased ...`, the
# message was queued at the OS level but the running `codex app-server` is not
# consuming stdin (common in runaway/infinite-loop sessions). In that state,
# you generally need to restart the VS Code extension host / app-server to make
# new messages take effect.

tail-codex-acp

tail-codex-acp --help

# Stream JSON-RPC notifications for ACP, one per line (tail -f style).
# By default, follow mode starts from "now" (no history).
tail-codex-acp -f 019c3bfa-43fd-78f0-ab40-758a1280a0a8

# Replay the last N events on connect, then follow
tail-codex-acp -f --history 50 019c3bfa-43fd-78f0-ab40-758a1280a0a8 | head

# Reopen-by-name follow mode (handles rotation/replacement)
tail-codex-acp --follow=name --history 50 019c3bfa-43fd-78f0-ab40-758a1280a0a8 | head

# Replay from start and exit
tail-codex-acp -n +1 --no-follow 019c3bfa-43fd-78f0-ab40-758a1280a0a8 | head

Output is newline-delimited JSON objects like:

{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"...","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"..."}}}}

Notes

• Session discovery defaults to $CODEX_HOME if set, otherwise ~/.codex.
• Both tools support -f/--follow[={name|descriptor}] to stream newly appended events (tail -f). Use --follow=name to reopen by filename (better when the log is replaced/rotated).
• For tail-codex-acp, use --history N to replay the last N events on connect (default: 0).
• Colors can be controlled with --color auto|always|never or NO_COLOR=1.