---
title: Agent reply formatting and showing images
---

# Agent reply formatting and showing images

## What it is

A reply from an agent is drawn as formatted text, not raw characters. Beyond ordinary
markdown, an agent can use a **fixed set of GitHub-style shapes** that GitHub users already
reach for, and it can **put a picture in front of you** — including one saved anywhere on
your computer.

## Where to find it

### Turning it off

The whole thing has a switch (Settings → Features, "Agent Markdown Formatting"), on by
default. With it off, every message is drawn exactly as it was before this existed — the
shapes above appear as the plain characters the agent wrote.

## How it behaves

### The formatting an agent can use

| Written as                                                            | Drawn as                                                                   |
| --------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `> [!NOTE]` / `[!TIP]` / `[!IMPORTANT]` / `[!WARNING]` / `[!CAUTION]` | A colour-coded block with its type name and an icon                        |
| `<div align="center">…</div>`                                         | Centred text                                                               |
| `<div align="right">…</div>`                                          | Right-aligned text                                                         |
| `<img src="…" width="400">`                                           | The image at that width instead of full size                               |
| `<details><summary>…</summary>…</details>`                            | A section you can open and close                                           |
| `<kbd>Ctrl+K</kbd>`                                                   | A keyboard key cap, drawn the same way the rest of the app draws shortcuts |
| `<mark>…</mark>`                                                      | Highlighted text                                                           |
| `<u>…</u>`                                                            | Underlined text                                                            |

Table columns also follow the alignment you specify in markdown — `| :---: |` centres a
column and `| ---: |` right-aligns it.

**Only those shapes are honoured.** Anything else an agent writes as HTML is shown as plain
text, exactly as characters — a deliberate limit, so a reply can never inject markup into the
app. Unrecognised callout types behave the same way: `> [!SOMETHING]` stays an ordinary quote
rather than being guessed at.

### Showing you a picture

An agent shows you an image by **handing the app a file path and the conversation to show it
in**. The app copies the file in and gives the agent back a markdown line; when the agent
writes that line into its reply, the picture appears.

- **Any image file on the machine works**, from any folder — not just the project it is
  working in. PNG, JPEG, GIF, WebP, SVG, BMP and TIFF, up to 50 MB.
- The picture is **visible only in the conversation it was shown in**.

#### What happens automatically

Separately from that, an agent that merely _mentions_ an image path in its reply has the file
picked up automatically — but only when it sits **inside the project the agent is working in**
and was **written during that same turn**. That narrow rule exists on purpose: without it,
narration like `` `icon.png` `` would silently attach whatever unrelated file happened to
match. The explicit route above is the way to show anything outside that.

#### When a picture cannot be shown

You are told why, in place of the image — never left with a blank gap. You may see:

- that the message pointed at **a file on the computer**, which a message cannot load
- that the picture **belongs to another conversation**
- that the message **gave no address** for it

A refusal from the explicit route says what was wrong and what to do about it — not an image
format, no readable file at that path, a file over the size limit, or a conversation id that
does not exist.

### Worth knowing

- **The app's own bracketed markers never appear on screen.** Tokens like
  `[[OMNISCIO_FINAL]]` are plumbing that tells the app where a message ends; they are removed
  before the message is drawn. That holds for one an agent invents, too — a made-up token is
  cleaned up rather than shown. To genuinely **display** a token like that, put it inside a
  code block or backticks, and it is left exactly as written.
- **Copying a message gives you the agent's original text**, not the formatted result — the
  drawing happens only on screen, so what you paste elsewhere is what the agent wrote.
- **Naming a file is not the same as showing it.** A path on its own tells you nothing you
  can open, which is why agents are taught to use the route above rather than print a path.

## Related

How an agent's prose and its tool activity are laid out in the feed is [Agent Message Display](agent-message-display.md). The interactive multiple-choice pills an agent can put inside its prose are [Question widget](question-widget.md), and a file you attach to your own message is [Chat attachments](chat-attachments.md).