tuicr Markdown Export Format and Clipboard Copy Behavior Explained

tuicr exports review sessions as structured Markdown documents and copies them to the system clipboard using a hierarchical fallback strategy that prioritizes native platform tools before falling back to OSC 52 escape sequences.

The tuicr code review tool provides a robust export system that transforms review sessions into portable Markdown documents. The implementation in src/output/markdown.rs handles both document generation and cross-platform clipboard integration, ensuring your review comments remain accessible whether you're working locally or over SSH.

How tuicr Generates Markdown Export Documents

The Markdown generation pipeline follows a strict assembly order defined in generate_markdown (lines 59–84, 94–105). Each export begins with validation in generate_export_content (lines 28–33), which ensures at least one comment or remote thread exists before proceeding.

Document Structure and Components

Exported Markdown documents contain eight distinct sections, each controlled by ExportConfig options parsed from config.toml in src/config/mod.rs (lines 42–65):

1. Session slug header — ## Session: {slug} when session_slug is provided (lines 69–72)

2. Custom intro line — Controlled by ExportConfig::intro (lines 76–80)

3. Scope banner — Context-aware description of what's being reviewed (lines 42–45, 86–98)

4. PR metadata — URL and head SHA for pull request reviews when pr_metadata is enabled (lines 99–101)

5. Comment-type legend — Lists enabled comment types with definitions when legend is true (lines 17–24)

6. Session summary — Summary: line from session_notes if present (lines 45–49)

7. Numbered comment list — Core review content

8. Remote-thread section — Unresolved GitHub threads for PR reviews (lines 65–84)

Comment Formatting Rules

Each comment line follows a precise pattern established in lines 50–55 and 22–38:

{i}. **[TYPE]** `path[:line]` (commit SHA) - {first-line}

• Type markers are omitted for untyped comments
• Location formatting distinguishes:
  • File-level comments (no line number)
  • New-side line ranges
  • Old-side (deleted) ranges prefixed with ~
  • Single-line ranges collapse to path:line rather than path:start-end
• Commit scoping appends short SHA in parentheses when applicable (lines 40–45)

Multiline comment bodies indent beneath the same list marker (lines 48–62).

Remote Thread Export Format

Unresolved GitHub comments appear after a configurable header (ExportConfig::remote_comments_header, default: ## Existing GitHub Comments). Threads group by file with this structure:

### `path`

{n}. `path[:line]` @author - {body}
    <url>
    - @reply_author - {reply_body}

This format appears in lines 65–84 of src/output/markdown.rs, consuming RemoteReviewThread data from src/forge/remote_comments.rs.

Cross-Platform Clipboard Copy Behavior

The export_to_clipboard function (lines 54–61) orchestrates copy operations through copy_text_to_clipboard, which implements a prioritized fallback chain:

Priority	Platform/Condition	Method	Implementation
1	macOS	pbcopy	try_clipboard_cmd("pbcopy") (lines 86–88)
2	All (configurable)	OSC 52	copy_osc52 when should_use_osc52() returns true (lines 89–92)
3	Wayland	wl-copy	try_copy_via_subprocess (line 14–15)
4	X11	xclip -selection clipboard	try_copy_via_subprocess (line 15–16)
5	Other UNIX	arboard crate	Clipboard::new().set_text (lines 96–100)
Final	All platforms	OSC 52 fallback	Retry after arboard failure (lines 100–102)

The function returns Result<bool> where true indicates OSC 52 was used as fallback, enabling user-facing messages to distinguish copy methods (lines 71–75).

OSC 52 Implementation Details

When terminal escape sequences are required, copy_osc52 (lines 142–162) handles tmux detection and buffer forwarding:

// Base64-encoded text wrapped in OSC 52 sequence
\x1b]52;c;<base64>\x07

Inside tmux, the command tmux load-buffer -w - forwards the buffer to the outer terminal. The write_osc52 helper (lines 198–204) performs base64 encoding and sequence emission.

Configuring Export Behavior

All Markdown and clipboard behavior is customizable through the [export] section of config.toml. The ExportConfig struct in src/config/mod.rs (lines 48–55) defines these fields:

Field	Default	Purpose
intro	Built-in sentence	Custom opening line
scope_line	true	Show "Reviewing..." banner
pr_metadata	true	Include PR URL and head SHA
comments_header	"## Local tuicr Comments"	Local comments section title

| remote_comments_header | "## Existing GitHub Comments" | Remote threads section title |

| legend | true | Show comment-type definitions |

Omitted keys fall back to defaults via ExportConfig::default.

Summary

• Markdown export in tuicr produces structured documents with numbered comments, scope context, and optional PR metadata—implemented in src/output/markdown.rs
• Comment formatting uses {number}. **[TYPE]** location (commit) - {summary} with intelligent line range collapsing and side indicators (~ for deletions)
• Clipboard copying prefers native tools (pbcopy, wl-copy, xclip) before falling back to OSC 52 escape sequences for SSH and terminal multiplexer environments
• Full configurability via [export] table in config.toml with sensible defaults defined in src/config/mod.rs

Frequently Asked Questions

What happens if no comments exist when I try to export?

The generate_export_content function validates that at least one comment or remote thread exists (lines 28–33). If the session is empty, the export aborts before generating Markdown or attempting clipboard operations.

Does tuicr work over SSH without X11 forwarding?

Yes. The OSC 52 fallback (lines 89–92, 100–102) writes escape sequences directly to stdout, allowing clipboard integration through terminal emulator support—even in headless SSH sessions. When running inside tmux, tmux load-buffer -w - bridges to the outer terminal's clipboard.

Can I customize the comment numbering or formatting?

The numbered list format is fixed, but you can disable individual sections via config.toml: set scope_line = false, legend = false, or pr_metadata = false to remove those elements. Comment type labels are defined in your configuration's [comment_types] section and appear upper-cased in export output.

Why does clipboard copy return Ok(true) even when failing?

The boolean return value indicates method used, not success status. true means OSC 52 fallback was employed; false means a native clipboard succeeded. This design ensures graceful degradation—if arboard fails (lines 96–102), the function retries OSC 52 rather than failing entirely.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}