Stream output to stdout: support -o - / /dev/stdout (#223 part 2)

[cboos]

Completes #223 (part 1 — the /dev/stdout version-sniff hang — landed in #237).

What

-o - (and -o /dev/stdout) streams the rendered document to stdout so it can be piped:

claude-code-log session.jsonl -f markdown -o - | pbcopy

Treated as: stream to stdout, always regenerate, no cache, no browser, and status/progress on stderr so stdout carries only the document. Supported for the main convert path and --session-id; --all-projects with -o - is a clear UsageError (it's a multi-file export).

How

Implemented in cli.py by reusing the full conversion pipeline via a throwaway temp file (_render_to_stdout): render with use_cache=False (so no pagination → a single document), force_regenerate, no individual session files, embedded images (the temp dir is discarded), then copy the file's bytes to sys.stdout. This keeps the streamed document byte-identical to the equivalent -o file output.

Status hygiene (only when streaming): the render runs inside contextlib.redirect_stdout, and any captured progress is forwarded to stderr — so an in-render print from any callee (e.g. the per-file Processing …) can't pollute the document stream. The pre-render Converting project path … echo is routed to stderr too when streaming. Every non-stream invocation keeps status on stdout exactly as today (no unconditional sweep — no behavior change for normal runs, including on PowerShell).

Cross-platform

- works everywhere. /dev/stdout is POSIX-only (on Windows the device doesn't exist and the path normalizes with backslashes, so detection won't match it there) — its test is skipif(win32); - is the portable form. No FIFO/mkfifo in these tests.

Tests

test/test_output_stdout.py (7): markdown/HTML/JSON document on stdout with stdout clean of status noise + confirmation on stderr; /dev/stdout no-hang (POSIX); - has no suffix so format inference doesn't fire; --all-projects + -o - errors; --session-id stream is clean (asserts no Processing/Loading on stdout). just ci green; no snapshot churn.

Closes #223

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added stdout-streaming for single-document exports: -o - and /dev/stdout now output only the rendered document bytes, with render-related messages sent to stderr.
  • Updated CLI help/behavior for streaming output, including format inference consistency for -.

• Bug Fixes

  • Blocked stdout streaming for multi-project (“all projects”) mode, and rejected --combined no with streaming.
  • Fixed the historical /dev/stdout hang issue on supported platforms.

• Tests

  • Added end-to-end tests covering Markdown/HTML/JSON streaming, stderr/stdout separation, Unicode round-trips, and invalid streaming combinations.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b260a4b0-8f2f-44da-a037-30b3c7a8bd89

📥 Commits

Reviewing files that changed from the base of the PR and between 7691fa8 and b4ae8f0.

📒 Files selected for processing (2)

• claude_code_log/cli.py
• test/test_output_stdout.py

🚧 Files skipped from review as they are similar to previous changes (1)

• claude_code_log/cli.py

---

📝 Walkthrough

Walkthrough

Adds CLI support for streaming rendered output to stdout for -o - and /dev/stdout, routes status and confirmation text to stderr, rejects streaming with --all-projects, and adds end-to-end tests plus matching notes.

Changes

CLI stdout streaming

Layer / File(s)	Summary
Stdout contract and helper plumbing claude_code_log/cli.py	Defines stdout targets and _render_to_stdout, updates --output help, and rejects stdout streaming with --all-projects.
Session-id stdout stream claude_code_log/cli.py	--session-id renders to a temporary file with caching disabled and embedded images, then streams the result to stdout.
Project conversion stdout stream claude_code_log/cli.py	Project-path conversion routes status text to stderr in stream mode and emits the combined document through the stdout streaming path.
Tests and notes test/test_output_stdout.py, work/tui-output-fixes.md	End-to-end tests cover stdout streaming behavior, and the work note is updated to match the implemented flow.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• daaain/claude-code-log#237: Hardens stdout-like output handling around /dev/stdout, which is the behavior this PR extends with streaming output.

Poem

🐇 I hopped through logs and found a clearer lane,
stdout now carries the document plain.
stderr hums softly with progress and cheer,
and /dev/stdout no longer stalls here.
Crunch, crunch—one carrot for the stream’s bright refrain!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 52.94% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: stdout streaming support for -o - and /dev/stdout.
Linked Issues check	✅ Passed	The changes implement stdout streaming, stderr routing, no-cache regeneration, and the all-projects rejection required by #223.
Out of Scope Changes check	✅ Passed	The added tests and docs directly support the stdout streaming feature and do not appear unrelated to the issue scope.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch dev/output-stdout-stream

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@claude_code_log/cli.py`:
- Around line 1234-1255: The stdout conversion path in cli.py’s
_render_to_stdout / convert_jsonl_to call is silently overriding an explicit
--combined no by forcing write_combined=True. Add a pre-check in the
stdout-target branch to detect when combined output was explicitly disabled and
reject it with a clear error instead of proceeding. Use the existing stdout
handling logic and the write_combined / generate_individual_sessions options to
locate the incompatible path.
- Around line 922-928: The stdout guard in cli.py is too broad because
will_run_all_projects becomes true for global --session-id usage, so it blocks
valid single-session exports before the session-resolution flow can run. Update
the check around _is_stdout_target(output) to reject only real multi-file
--all-projects exports, and allow the single-session path used by the later
session lookup logic so claude-code-log --session-id <id> -o - continues to
work.
- Around line 70-76: The _render_to_stdout path is treating the rendered file as
text instead of bytes, which can re-encode or corrupt output on non-UTF-8
stdout. Update the _render_to_stdout logic in cli.py to read the temp file as
raw bytes from the Path returned by written, then write those bytes directly to
stdout via sys.stdout.buffer while leaving the captured progress handling
unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 9bd51d24-f803-4768-89f1-d3816055e8f7

📥 Commits

Reviewing files that changed from the base of the PR and between c4fb92f and 7691fa8.

📒 Files selected for processing (3)

• claude_code_log/cli.py
• test/test_output_stdout.py
• work/tui-output-fixes.md