Artifacts

Artifacts are durable documents, interactive pages, visual boards, and files inside a Task. They keep plans, work items, and review findings where you and your agents can both find them, instead of leaving them buried in a chat transcript. The Artifacts panel shows the Task’s artifact tree. Open an artifact to read, preview, or edit it in a panel. See Editing artifacts.

Artifact Types

Type	Use it for	Status
Spec	Durable context: goals, requirements, constraints, decisions, plans, and walkthroughs.	No
Ticket	A unit of implementation work: what needs to change and how to verify it.	Yes
Story	A group of related artifacts, such as the tickets and specs that serve one user journey.	Yes
Review	Review findings, critique, decisions, and follow-ups.	No
HTML	Interactive reports, charts, explainers, and pages. See HTML artifacts.	No
Canvas	Screens, mockups, and flows on a visual board. See Canvases.	No
File	PDFs, Word documents, images, text, and other deliverables. See File artifacts.	No

Specs and reviews are shared context. Tickets and stories track work, so they carry a status.

Hierarchy

Artifacts can nest under other artifacts. Folder-based artifacts can have children; a standalone file has no Add child artifact control. A common shape:

Task
└─ Spec
   ├─ Ticket
   ├─ Story
   │  └─ Ticket
   └─ Review

Only artifacts nest in this tree. Agents are listed in the Agents panel and can’t be placed under an artifact. Drag an artifact in the panel to change its parent. An artifact can’t be moved into its own subtree.

Status

Tickets and stories have one of three statuses. New tickets and stories start as Todo.

Status	Meaning	Value in the file
Todo	Work exists but has not started.	`0`
In Progress	Work is underway.	`1`
Done	Work is complete.	`2`

Change the status with the status pill at the top of an open ticket or story. Viewers see the pill but can’t change it. The value column is what appears in the artifact’s file on disk; see Artifacts on Disk.

Panel Controls

The panel header has three controls:

Control	What it does
Add artifact (+)	Creates a top-level artifact: New ticket, New spec, New story, New review, or New canvas. HTML and file artifacts are created from files, usually by an agent.
More artifact actions (⋯)	Opens Search artifacts, Deleted artifacts, Collapse all, and Select artifacts.
Filter artifacts	Sets the ordering and filters, described below.

Each row also has its own controls when you hover it:

Add child artifact (+) creates a new artifact nested under that row, with the same choices.
The row’s ⋯ menu, also available by right-clicking the row, has Rename, Copy ID, and Delete. Markdown documents also have Export as Markdown and Export as PDF; HTML and file artifacts have download controls in their open panels.

Filter and Order

Filter artifacts opens these options:

Option	Choices
Ordering	Last updated, Date created, or Name; Descending or Ascending.
Status	Todo, In Progress, Done.
Type	Spec, Ticket, Story, Review, HTML, Canvas, File.
Read state	All, Unread, Read.

The menu also has Mark all as read and, once you have changed anything, Reset view. Only tickets and stories have a status, so any Status filter hides other types.

Read and Unread

A thin bar beside a row marks an artifact that changed since you last opened it (Unread artifact). A collapsed row whose children include unread artifacts shows a fainter bar (Contains unread artifacts). Opening an artifact marks it read. Read state is kept per device, so each collaborator and each of your devices has its own view of what’s new.

Search

Search artifacts in the ⋯ menu replaces the header with a search field. Typing while the tree has focus starts a search too, and Esc closes it. Search matches artifact titles, folder paths, and body text. It reads the Task’s files on disk, so it isn’t offered to Viewers, or in a Task with no artifacts yet.

Select Several Artifacts

Choose Select artifacts from the ⋯ menu, or ⌘-click / Ctrl-click rows. The header then shows how many are selected, with Select all, Cancel selection, an export button, and a delete button. See Export.

Reference an Artifact in Chat

Type @ in an agent message and choose Artifacts, then select the artifact by title. The same list includes Markdown documents, HTML artifacts, canvases, and file artifacts. Use the reference to ask for a change or direct the agent to a particular deliverable. Nothing is sent until you send the message.

Working With Artifacts

Action	How
Create	Add artifact (+) in the header, or Add child artifact (+) on a row.
Rename	Rename in the row menu. The title shows in the panel, the tab, and references to the artifact.
Move	Drag the row onto its new parent.
Change status	Use the status pill at the top of an open ticket or story.
Comment	Select document text, or comment on an HTML element or canvas. See Comments.
Export	Markdown/PDF for documents; download controls for HTML and files. See Export.
Delete	Delete in the row menu. This also deletes the artifacts nested under it.

Creating, editing, moving, and deleting artifacts needs the Editor or Owner role. See Roles.

Deleting and Restoring

Deleting an artifact removes it, and every artifact nested under it, from the tree. You can bring deleted Markdown documents back from Deleted artifacts in the panel’s ⋯ menu. See Version history and recovery.

Artifacts on Disk

The on-disk format depends on the artifact:

Specs, tickets, stories, and reviews: an index.md document, synced with the editor.
HTML: a folder with index.html and its supporting files.
Canvas: a folder with canvas.json, board HTML files, and supporting files.
File: a standalone deliverable, such as a PDF or image.

These artifacts sync with the Task, so collaborators can open the published deliverables without sharing your repository folder. The workspace itself is separate; see File Tree. A host keeps its copy current only while the Task is open there or one of its agents is working in it. Elsewhere the copy is the one that host last had, and it can be out of date or missing artifacts until the Task opens there again. The copy exists only for people with the Editor or Owner role. Viewers have no files on disk.

~/.traycer/epics/<task-id>/artifacts/
└─ <artifact-folder>/
   ├─ index.md
   ├─ .comments/
   │  └─ <thread-id>.md
   └─ <child-folder>/
      └─ index.md

For Markdown documents:

Each artifact is a folder, named after the artifact’s title when it was created, that holds an index.md.
Nested artifacts are nested folders.
A new folder with an index.md becomes a new artifact in the Task. This is how agents create artifacts.

For Markdown documents, index.md and the .comments/ files sync between hosts and to collaborators. An artifact’s images/ folder holds copies of the images in that artifact, which each host writes for itself. The host keeps that folder matching the artifact, so a file you add there is removed, and one you change or delete is put back. Other deliverable files beside index.md can become separate file artifacts. HTML and canvas folders also sync their supporting files; they are not limited to Markdown. Each index.md starts with frontmatter:

---
title: "Offline mode"
kind: ticket
status: 1
comments: 2 open, 1 resolved
---

Field	Meaning
`title`	The artifact’s title.
`kind`	`spec`, `ticket`, `story`, or `review`.
`status`	Tickets and stories only: `0` Todo, `1` In Progress, `2` Done.
`comments`	Written by Traycer: `none`, or counts such as `2 open, 1 resolved`. It can lag behind the app.

Comment threads are copied into a hidden .comments/ folder beside the artifact, one file per thread. Agents read those files, and resolve a thread by changing its status: line. See Comments and Agents. Agents can work with these files using ordinary file tools. For HTML and canvas artifacts, sync messages and comment counts are reported in status.txt beside the artifacts folder.

HTML artifacts

Interactive pages, inline previews, and ZIP downloads.

Canvases

Review and edit visual boards, screens, and flows.

File artifacts

Preview and download shared deliverables.

Editing

The editor toolbar, links, images, and sending passages to a chat.

Version history and recovery

Compare and restore earlier versions, and bring back deleted artifacts.

Export

Save documents as Markdown or PDF, or download HTML and files.

Diagrams

Mermaid diagrams that render inline.

Wireframes

Live HTML previews of proposed screens.

Artifact workflow

The skills agents use to plan, build, and review with artifacts.

Get Started

Guides

Concepts

Panels

Agents & Models

Account

CLI

Reference

Changelog

Artifact Types

Hierarchy

Status

Panel Controls

Filter and Order

Read and Unread

Search

Select Several Artifacts

Reference an Artifact in Chat

Working With Artifacts

Deleting and Restoring

Artifacts on Disk

More on Artifacts

HTML artifacts

Canvases

File artifacts

Editing

Version history and recovery

Export

Diagrams

Wireframes

Artifact workflow

​Artifact Types

​Hierarchy

​Status

​Panel Controls

​Filter and Order

​Read and Unread

​Search

​Select Several Artifacts

​Reference an Artifact in Chat

​Working With Artifacts

​Deleting and Restoring

​Artifacts on Disk

​More on Artifacts

HTML artifacts

Canvases

File artifacts

Editing

Version history and recovery

Export

Diagrams

Wireframes

Artifact workflow

Artifact Types

Hierarchy

Status

Panel Controls

Filter and Order

Read and Unread

Search

Select Several Artifacts

Reference an Artifact in Chat

Working With Artifacts

Deleting and Restoring

Artifacts on Disk

More on Artifacts