File Attachments

Attachments are files associated with a task or a message within a task. They can be added at two points: when a task is first created, or inline with any reply message. Every attachment is stored server-side and referenced by its attachment ID. Each stored file also gets a public link, which is how the dashboard downloads it and how an agent can fetch it without pulling base64 through MCP.

The dashboard provides two places where you (the human) can attach files, with the "Attach files" button or by drag and drop. These attachments become part of the task's message thread and are visible to both you and any connected Claude Code agent.

Both task create and task reply accept an optional attachments array in their payload. Each attachment object carries the file content as base64-encoded data so it can be transmitted over the MCP protocol and stored server-side.

Example: Claude has finished reviewing code changes and wants the human to approve a diff before merging. It creates a task with the diff attached:

task {"action": "create", "payload": {
  "title": "Review this diff",
  "body": "I've made the changes — here's the diff for your review.",
  "attachments": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "filename": "changes.diff",
      "mimeType": "text/plain",
      "data": "base64encodedcontent..."
    }
  ]
}}

The same pattern works with task reply — Claude can attach a screenshot of a test result, a generated report, or error logs as part of a progress update:

task {"action": "reply", "payload": {
  "taskId": "TASK_ID",
  "text": "Tests are passing. See attached output for details.",
  "attachments": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "filename": "test-output.txt",
      "mimeType": "text/plain",
      "data": "base64encodedcontent..."
    }
  ]
}}

Files travel base64-encoded, which makes them a third larger, and a single request is capped at 4 MB. Keep the files on one task or message under about 3 MB in total.

agentrq-ws reply TASK_ID "Build is green — log attached" --attach ./run.log
agentrq-ws task create "Review the design" --body @brief.md --attach ./mock.png
agentrq-ws attachment get ATTACHMENT_ID --task TASK_ID --out ~/Downloads

When a human attaches a file to a task or message, Claude Code sees it listed under Attachments: with its ID, name, type and, when the file has one, a public link. The getAttachment action of the task MCP tool looks the ID up on the task and its messages. By default it returns that link instead of the file, so a large PDF does not fill the agent's context. Ask for base64 when the agent needs the bytes.

task {"action": "getAttachment", "payload": {"attachmentId": string, "taskId": string, "format"?: "url" | "base64"}}

Returns:
  { filename, mimeType, url }    // format "url" (default), when the file has a link
  { filename, mimeType, data }   // format "base64", or when there is no link

// data is the file content, base64-encoded.

Clients installed before the action tools may still call createTask, reply (with chatId) or getAttachment by their old names. Those calls still work: the server maps each one to the matching task action. See Old tool names.

A typical workflow: the human attaches a specification document when creating a task, and Claude reads it before beginning work.

// The task notification lists the attachment:
// Attachments:
//   - id=0jN4sT2kQ8p name=payment-spec.pdf type=application/pdf url=https://…

task {"action": "getAttachment", "payload": {"attachmentId": "0jN4sT2kQ8p", "taskId": "TASK_ID", "format": "base64"}}

// Returns:
{
  "filename": "payment-spec.pdf",
  "mimeType": "application/pdf",
  "data": "JVBERi0xLjQKJcfsj6IK..."
}