Skip to content

Attachments

Attachments are files uploaded to an issue. They are stored on the Trimus server filesystem (under TRIMUS_STORAGE_DIR) and indexed in the database. Attachments with extractable text are read by the agent working the issue.

Supported formats for agent context

Format Extension(s) Behaviour
Text .txt, .csv, .json, .yaml, .yml, .go, .py, .ts, .js, … Agent sees the content verbatim.
Markdown .md, .markdown Same.
PDF .pdf Agent sees extracted text (one read per page; via ledongthuc/pdf). Image‑only PDFs return no text — agent sees a stub.
Anything else .docx, .xlsx, .png, .jpg, … Upload succeeds; agent sees a "content unavailable" stub. Office docs and images are not extracted.

Caps and limits

Configured via environment variables (see environment.md):

Variable Default Effect
TRIMUS_ATTACHMENT_MAX_UPLOAD_BYTES 50_000_000 (50 MB) Per‑file upload cap. Larger returns 413.
TRIMUS_ATTACHMENT_MAX_FILES_PER_REQUEST 20 Multipart file‑count cap.
TRIMUS_ATTACHMENT_EXTRACT_TIMEOUT_SEC 5 Per‑attachment extraction timeout. Timeout → empty extracted text.
TRIMUS_ATTACHMENT_EXTRACTED_TEXT_MAX_BYTES 200_000 Per‑row cap on stored extracted text. Truncated with a marker if exceeded.
TRIMUS_ATTACHMENT_CONTEXT_CHAR_LIMIT 50_000 Total cap across all attachments rendered into agent context per turn.

The global TRIMUS_MAX_UPLOAD_SIZE (25 MB) is a separate multipart cap; the per‑attachment cap above governs individual attachment files.

How the agent sees attachments

When a heartbeat run fires on an issue, the engine builds a ## Attachments block in the agent's context. Most recently uploaded attachments come first; files past the character budget are truncated (with a marker the agent can pass through to the user) or skipped with a "budget exhausted" stub.

The /get-issue chat verb surfaces only attachment metadata (file list, sizes) — full extracted content is reserved for the heartbeat run.

Attachments with no extracted text

An attachment whose extracted_text is NULL (an unextracted format, a timed‑out extraction, or an upload from before extraction was wired) shows as a "content unavailable" stub. To make it readable, delete and re‑upload it in a supported format.

Upload paths

  • Web UI — the issue page and the new‑issue form accept inline file uploads.
  • JSON API (single file) — POST /api/issues/{id}/attachments (multipart, one file per request).
  • JSON API (with issue creation) — POST /api/issues with multipart/form-data: embed files as repeated file parts alongside the text fields (title, body_markdown, …). Response is {issue, attachments, attachment_errors?}.
  • Chat — attaching files from a Slack/Telegram DM is not supported; create the issue via chat, then attach via the UI.

Where to next