# tuicr Markdown Export Format and Clipboard Copy Behavior Explained

> Understand the tuicr Markdown export format and clipboard copy behavior. Learn how tuicr exports reviews hierarchically using native tools or OSC 52 fallback.

- Repository: [Almog Gavra/tuicr](https://github.com/agavra/tuicr)
- Tags: api-reference
- Published: 2026-08-02

---

**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](https://github.com/agavra/tuicr) code review tool provides a robust export system that transforms review sessions into portable Markdown documents. The implementation in [`src/output/markdown.rs`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/config.toml) in [`src/config/mod.rs`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/src/output/markdown.rs), consuming `RemoteReviewThread` data from [`src/forge/remote_comments.rs`](https://github.com/agavra/tuicr/blob/main/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:

```rust
// 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`](https://github.com/agavra/tuicr/blob/main/config.toml). The `ExportConfig` struct in [`src/config/mod.rs`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/config.toml) with sensible defaults defined in [`src/config/mod.rs`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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.