---
title: Artifacts
description: Pages, documents, and diagrams agents show beside the conversation — versioned, commentable, and shareable with a person, a team, or the web
updated: "2026-11-15"
---

## Overview

An **artifact** is something an agent made for you to look at: a report, a plan, a code review, an architecture
diagram, a dashboard of measured numbers, a clickable prototype, or a small form that asks for your decision. The
agent writes it as an ordinary file in its worktree and publishes it with `dev artifact publish`. Agentastic keeps
every version, opens it in an **Artifacts** tab beside the agent, and lets you comment on parts of it, share it, and
send your comments back to the agent.

Artifacts work the same for agents on this Mac, on [Remote SSH](/docs/features/agents) hosts, and on cloud nodes.
On a remote host the agent's `dev` reads the files there and sends them to the app, so nothing on the host needs
to be reachable from your Mac. If your Mac is asleep or offline when the agent publishes, the host keeps the page
and delivers it when your Mac reconnects; it then opens like any other. Agents in a
[worktree container](/docs/how-to/containers#attachments-skills-plugins-and-artifacts) get a `dev` that hands
`dev artifact` commands to the app through the container's home folder. They can publish only files inside their
worktree, and can't delete artifacts.

Every agent learns about artifacts from the built-in **Artifacts** plugin (Settings → Plugins), which delivers the
`artifacts` [skill](/docs/features/skills) to each run. Turn the plugin off there to stop it.

## What an artifact can be

| Source | Shows as |
|---|---|
| `notes.md` | A styled document; ```` ```mermaid ```` fences are drawn as diagrams |
| `flow.mmd` | A Mermaid diagram |
| `report.html`, or a folder with `index.html` and its assets | The page as written |
| `.png`, `.jpg`, `.svg`, `.gif`, `.webp` | The image |

HTML artifacts load Agentastic's design system, the same one [Manager Agents](/docs/features/manager-agents) use,
so a page written with its classes follows your theme in light and dark mode. Pages run sandboxed: scripts may load
from a few CDNs (jsDelivr, unpkg, cdnjs, Tailwind, Google Fonts), and a page can't fetch from or post to anything
else. A folder may hold up to 500 files and 50 MB (20 MB when published from a remote host).

## Viewing and versions

Publishing opens the artifact in an Artifacts tab in the agent's worktree. If you're looking at another worktree,
Agentastic notifies you instead of switching, and the same holds when an agent opens one later with
`dev artifact open`. The agent's [chat](/docs/features/chat#artifact-pins) also keeps a pin for
the artifact above its prompt, which reopens it with one click until you dismiss it with its **×**. **View → Artifacts** opens the gallery: every artifact with a thumbnail,
filtered by **All**, **Shared**, and **Archived**, with search. Artifacts your teams shared with you appear there
too.

Each publish of the same path adds a version. The version menu in the tab's toolbar shows them all with what changed,
and you can open any of them. Publishing identical files adds nothing. The toolbar also reloads the page, exports a
PNG, and renames, archives, or deletes the artifact.

Click a `codeedit://artifact/…` link anywhere in the app (an agent prints one after publishing) to open the
artifact. The same link opens it in the [companion app](/docs/features/companion#open-artifacts) on your phone,
with its versions and working forms, in the phone's light or dark appearance.

## Comments and feedback

Select text on the page and a comment composer appears beside it: the same one the
[Markdown editor](/docs/features/markdown) and the [diff viewer](/docs/features/diffs) use. Start typing (or click into
it), then choose where the comment goes:

| Destination | What happens |
|---|---|
| **Agent** | The comment is sent right away to the agent that published the artifact |
| **Comment** | The comment is kept on the page, to send later |

Press <kbd>Return</kbd> to send or save, <kbd>Shift</kbd>+<kbd>Return</kbd> for a new line, and <kbd>Esc</kbd> to close
the composer. Right-clicking a selection offers **Ask Agent About Selection** and **Comment on Selection**, with the
same shortcuts as in Markdown documents.

The passage you commented on stays highlighted, with a numbered marker; click it to open its thread in the comments
panel (the speech-bubble button in the toolbar). To comment on a whole element instead, such as a chart or an image,
click the target button in the panel and then the element. The **+** button comments on the page as a whole.
Comments are anchored to the text itself, so they find their passage again on later versions; a thread whose text
is gone says so.

Comments go to the agent's chat, its terminal (when an agent is running there), or, for a Manager Agent, its mail.
Comments you kept for later go with **Send New Comments to Agent** in the panel's menu. The agent edits the source,
publishes a new version, replies in the thread, and resolves what it fixed.

Comments people leave on a shared copy come back the same way. Agentastic checks for them while the app runs and
delivers them to the agent automatically, at most 60 times an hour for each artifact.

Readers' comments reach the agent marked as untrusted text: information about the page, never instructions that
override you.

## Interactive pages

A page can collect answers and keep shared data through `window.agentastic`, the same API Agentastic Sites uses,
so it behaves the same in the app and once shared:

- A `<form data-agentastic>` sends its fields to the agent as one response; `agentastic.submit()` and
  `agentastic.ask()` do the same from script.
- `agentastic.data` stores records in collections declared in an `agentastic.json` beside `index.html` (votes, a
  shared checklist, a triage board). Records survive republishing, conflicting writes fail cleanly, and open pages
  update live. Agents read and write the same records with `dev artifact data`, and edits people make on a shared
  copy are copied back to the app while it runs.

When people change the shared data of a page a Manager Agent owns, in the app or on a shared copy, the manager wakes
up to look.

The `artifacts` skill ships three starting points agents can copy: a findings report, a decision page with a form,
and a shared board people add to and vote on.

## Sharing

Click **Share** in the tab's toolbar. Sharing uploads a copy to Agentastic Sites, so you need to be signed in to your
Agentastic account (Settings → Accounts).

| Option | Who can open it |
|---|---|
| **Live link** | Anyone with the link, while Agentastic runs. Served from this Mac through a temporary tunnel; nothing is uploaded |
| **Links for people** | One link per person, each with a label, a permission, and an expiry, and each revocable on its own |
| **Teams and shared spaces** | Members of the [teams](#teams) and shared spaces you pick, signed in, without a link |
| **Public page** | Anyone, at `<name>.agentastic.site`; optionally indexed by search engines |

Permissions: **Can view** opens the page and reads its data, **Can comment and respond** also sends comments and
form responses, **Can edit data** also writes shared records.

By default the shared copy follows new versions. Turn off **Update the shared copy when a new version is published**
to keep readers on the version they have, and use **Update Now** when you're ready. **Stop Sharing** deletes the
shared copy; every link stops working and the artifact stays on your Mac.

Before uploading, Agentastic scans the files for credentials and warns you about anything that looks like one. An
agent can ask to share with `dev artifact share`, but every share it asks for waits for you to approve it.

## Teams

Create a team in **Settings → Accounts → Agentastic → Teams**, then invite people with a link you send them.
Owners and admins manage members and invite links; members see what the team shares in the Artifacts gallery and
can open it signed in. Sharing with a team is a choice in the Share popover, alongside links for individual people.

The same popover lists the [spaces you share with a team](/docs/features/spaces#sharing-a-space-with-a-team).
Sharing an artifact with one lists it in the space, where everyone in the space can open it. Each member opens it
with a link of their own, which ends when they leave or you stop sharing.

## Manager Agents

A Manager Agent's pages (`dev manager page`) are artifacts it owns. The page header has **Open as artifact** and
**Share**, so a manager's dashboard page can be versioned, commented on, and shared like any other. Comments and
responses arrive in its mail. `dev memory publish <page>` publishes a wiki page, and an artifact one of its workers
publishes appears in its feed as an output.

## For agents

```sh
dev artifact publish .agentastic/artifacts/q3-review --title "Q3 review"
dev artifact render <artifact> --out /tmp/q3.png
dev artifact comments <artifact>
dev artifact comments reply --thread <id> "Fixed in version 3"
dev artifact comments resolve --thread <id>
```

Agents write artifacts under `.agentastic/artifacts/` in the worktree; Agentastic adds that folder to the
repository's `.git/info/exclude` so the sources stay out of your git status. The full command list is in the
[dev CLI reference](/docs/reference/dev-system#artifacts-artifact).

## Where it's stored

Artifacts live in `~/Library/Application Support/Agentastic.dev/Artifacts/`: a database of artifacts, versions,
comments, and shared data, beside the files of every version, stored once by content. Deleting an artifact removes
its versions and comments, and takes its shared copy down.
