Docs

Comments, attachments, and artifacts

The three kinds of context a task can collect, and when to use which.

Tasks can collect context in three different forms. They look similar in the UI but serve different purposes, and choosing the right one keeps tasks readable months later.

Comments

Use comments for ongoing discussion: questions, updates, reviews, short decisions. Comments are conversational — ordered by time, attributed to a person, and best when each one is small.

Attachments

Use attachments for raw files: screenshots, design exports, logs, images, documents. Image attachments can be previewed directly in the UI. Attachments preserve the file as-is; nothing edits them in place. One exception: attaching an .html file creates an html artifact (see below) instead of an attachment, so it can be rendered in the UI.

Artifacts

Artifacts are durable documents attached to a task: plans, reviews, implementation notes, handoff documents. Most artifacts are markdown, which you can edit in place in the task sidebar. Artifacts can also be html — for example a report or interactive preview produced by an agent or uploaded from a file — which render read-only in a sandboxed frame, with a button to open them in a full page. Unlike comments, artifacts are meant to be revised in place and revisited — a plan artifact evolves as the plan does, instead of being buried under newer comments.

Artifacts are also the main hand-off surface for AI workflows:

  • AI clients connected through MCP can create, read, and edit artifacts (create_task_artifact, replace_in_task_artifact, …)
  • the same operations are scriptable via convoy tasks artifacts ...

A common pattern: an agent writes its implementation plan as an artifact, teammates review it in the task sidebar, and the agent updates it as work progresses.

Moving a resource to another task

Filed something on the wrong task? Drag its pill from the task's Resources section onto any task row — in the project table or in the subtasks list of an open task — and it moves there. This works for both attachments and artifacts, and the artifact's comments follow it. The target task must be in the same project, and dragging is desktop-only.

The same move is scriptable:

  • convoy tasks artifacts move <artifactId> --to-task <taskId>
  • convoy tasks attachments move <taskId> <attachmentId> --to-task <taskId>

AI clients can move artifacts through MCP (move_task_artifact).

Rule of thumb

  • Comments for conversation.
  • Attachments for raw files.
  • Artifacts for durable document deliverables (markdown or html) that should stay easy to find and revise.

Tasks

The core work item — refs, statuses, views, subtasks, and ordering.

AI threads

Persistent AI conversations that execute on a connected machine and stream back into the app.

On this page

CommentsAttachmentsArtifactsMoving a resource to another taskRule of thumbRelated pages