# artifact

Part of [pi-suite](../../README.md). Turn it off with `/suite off artifact`.

Summaries, reports and overviews saved as pages and opened in your browser. Ask for one ("make me an artifact of this"), or run `/artifact`. Everything else stays in the terminal.

## Use

| Command | What it does |
|---|---|
| `/artifact` | Turns this conversation into a page |
| `/artifact <topic>` | A page about that topic |
| `/artifacts` | Opens a saved page, or the list of them all |

The agent writes Markdown and the `artifact` tool turns it into the page, so a page costs about the same tokens as the same answer in chat. To change one, the agent edits its `.md` file and the page is drawn again, rather than the whole document being written again.

## Where they're kept

`~/.pi/agent/artifacts/`: each artifact is a `.md` file you can read, grep or edit, and an `.html` page next to it. `index.html` lists them all. Nothing leaves your machine.

## What a page can show

Headings, lists, tables, code, links, a contents list once there are three sections, callouts written as `> [!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]` or `[!CAUTION]`, and Mermaid diagrams. Light and dark follow your system.

Diagrams are drawn as box art, the same drawing Pi shows in the terminal, for `flowchart`, `sequenceDiagram`, `stateDiagram-v2`, `classDiagram` and `erDiagram`. Other types show their source.

## Security

A page is built from what the model wrote, and the model may have read the web. So a page can't run anything:

- Raw HTML in the Markdown shows as text.
- Only `https`, `http`, `mailto` and `#` links are kept. Images show as their description.
- Each page forbids scripts and loading anything from elsewhere, in case something gets past the rest.

In `auto`, the tool runs without the judge, as it only writes to its own folder.

## Limits

- **No sharing.** Pages are local files. Send the `.html` file if someone else needs it.
- **No images, charts or math rendering.** Math shows as written.
- **Opening needs `open` (macOS) or `xdg-open` (Linux).** Elsewhere, the tool gives the path instead.