Attachments
Attach files, folders, past chats, issues, pull requests, and images to your Agent Chat prompts.
Agent Chat lets you attach context to a message instead of pasting it inline. Attachments show up as inline chips in the composer and get expanded into the prompt at send time.
This is part of the default Agent Chat GUI. Attachments are unavailable only if you opt back into the classic terminal-first interface.
Attachment Types
| Type | Trigger | What it injects |
|---|---|---|
| File | @, + picker | Contents of the file, wrapped with a path header (large files: the first 50 lines plus an outline) |
| Folder | @, + picker | A depth-bounded tree of the folder, with a pointer for the agent to Read or Grep what it needs |
| Chat | @session:, + picker | A past conversation from this workspace — see Conversation Handoffs |
| Issue | + picker (search by number or title) | Title, state, labels, assignees, body, and up to 20 comments |
| Pull / merge request | + picker (search by number or title) | Title, state, branches, stats, body, comments, and the changed files (or the full diff) |
| Image | + picker, drag-drop, clipboard paste | Sent as a multi-modal message (provider-dependent) |
The + Popup
Click the + icon in the composer footer to open the popup. Besides the chat modes and integrations, its Attach group has:
- File… — fuzzy-search your project's files.
- Folder… — attach a directory tree.
- Image… — pick an image from disk. Disabled, with "Current model doesn't support images", when the selected model can't take images.
- Chat… — hand off another conversation's context (needs a workspace).
- GitHub Issue… (or your host's equivalent) — search this repo's issues by number or title.
- GitHub PR… / GitLab MR… — the same for pull or merge requests.
Issue and request rows are disabled, with the reason, when the repo has no supported host or the host's CLI is missing or signed out. The popup dismisses on outside click (Esc also works).
@ Mentions
Typing @ in the composer opens a fuzzy file picker inline. Select a file and it becomes an attachment chip the same way the + picker does. Faster for "I know the filename" cases.
Drag and Drop
- Images from your file manager, browser, or screenshot tool — drop anywhere on the composer. The drop target highlights while you drag a file over it.
Dropping non-image files doesn't attach them; use @ or the + picker for files and folders.
Clipboard Paste
You can paste images directly into the composer with Ctrl+V (or the platform equivalent). This works for:
- Screenshots from
grim, the GNOME Screenshot tool, Snipping Tool, etc. - Images copied from a browser (right-click → Copy Image).
- Images on your clipboard from any other source.
The paste also works on the new-workspace prompt input, so you can drop a screenshot straight into the "What do you want to do?" textarea when creating a workspace.
Inline Chips
Attached items show up as compact chips in the composer footer, above the textarea. Each chip shows:
- Type icon — file, folder, issue, or PR. An image chip leads with a real thumbnail of the image itself instead, so two pasted screenshots are no longer indistinguishable; the generic icon appears only while the image is still resolving, if it fails to decode, or where previews aren't available.
- Label — filename, folder name,
#42for issues,PR #137for PRs. - Tooltip on hover — full path or URL. For an image, a larger preview above the filename, token estimate, and file size.
- Expand button — preview the content that will be injected. On a pull request chip it toggles between Show full diff and Show filenames only.
- Remove button — drop the attachment.
Send-Time Injection
When you hit Send, attachments are expanded into the underlying API request:
- Files — wrapped with a path header and line count. Large files send the first 50 lines plus an outline of declarations and tell the agent to Read the rest; binary files are left for the agent to read itself.
- Folders — a depth-bounded tree rather than every file's contents, so a big folder doesn't flood the prompt; the agent reads what it needs.
- Issues and requests — fetched through the host's CLI (
ghorglab) when attached, and fetched again at send time if the chip is more than a minute old, so you get current state. Pull requests send the list of changed files by default, or the diff (capped at 100 KB) when you toggled Show full diff. Rows are disabled with the reason when the CLI is missing or signed out — see Pull & Merge Requests. - Images — sent as multi-modal content blocks where the model supports it. Hermes doesn't take image attachments, and a custom ACP agent only does when it advertises image support. Once sent, an attached image renders inline in your message bubble (small, with a broken-image fallback); click it to open a full-size lightbox.
Caps and Safety
- 20 attachments per message, of which at most 3 can be chats.
- Image types — PNG, JPEG, WebP, and GIF. Other types are refused with a toast.
- GIF guard — animated GIFs are rejected with a friendly warning ("Save as PNG or JPEG instead.") instead of silently failing the request.
- Image size warning — a non-blocking warning appears when the staged images add up to more than 5 MB.
- Large files and folders are summarised rather than pasted whole (see above), and issue bodies, comment threads, and PR diffs are capped.
Related
- Agent Chat — the chat pane these attachments live in
- Workspaces — the new-workspace prompt input also accepts image paste
- Pull Requests — the source of the PR data attachments