present-file

name	present-file
description	Hand the user a file from a Forge session — it appears in their Lexi app as a tappable card that opens in the file preview. Use for finished deliverables (reports, images, PDFs, diagrams, screenshots, charts, build artifacts).

present-file — deliver a file to the user

In a Forge coding session you can hand the user any file on the host and it shows up in their app as a tappable card that opens in the built-in file preview (QuickLook). This is the in-app, durable analogue of the harness SendUserFile tool — it works over the Forge data plane, so it reaches the Lexi app (not just claude.ai).

Usage

present-file <path> [--caption "short note"] [--title "Display Name.ext"]

• <path> — any file on the host. Absolute or relative; inside OR outside the workspace — a /tmp scratch artifact works exactly like a repo file (the broker stages a copy).
• --caption — a short line shown under the card (optional).
• --title — override the display name (defaults to the file's basename).

On success it prints {"file_id": "...", "name": "...", "size": ..., "mime": "..."}. On failure it prints the error and exits non-zero (missing file → exit 4, too large → the broker returns 413).

Examples

present-file /tmp/report.pdf --caption "The Q3 analysis you asked for."
present-file apps/chat/build-screenshots/build-42/dashboard.png --title "Build 42 — Dashboard"
present-file /tmp/diagram.svg

When to use it

• Do use it for finished deliverables the user would want to open or keep: a generated report, a rendered chart/diagram, a screenshot, a produced PDF, an exported artifact.
• Don't use it for routine tool output, logs, or intermediate scratch files — those belong in the normal transcript, not as a delivered file.

How it works (for the curious)

A per-session broker PATH shim POSTs the resolved absolute path to a loopback endpoint. The broker stages a copy under the session home (outside the workspace, survives restart), mints an opaque file_id, and emits the file as a self-contained assistant turn carrying a present_file tool_use block. The app renders that as the card and fetches the bytes by opaque id (never by path). Engine- agnostic: it works the same in Claude Code and Codex sessions.