File References in Messages

Reference files and commands directly in your prompts:

• @src/file.ts — include the file's content in your prompt.
• !`git log --oneline` — run a shell command and embed its output.

These work in both interactive TUI messages and in neusiscode run "prompt".

File attachments (images and PDFs)

When you reference or read a file whose content is an image or a PDF, Neusis Code attaches it to the message as media rather than as plain text. The read tool detects the type by sniffing the file's bytes (PNG, JPEG, GIF, BMP, WebP, and PDF magic numbers), so a file is treated as media based on its real contents, not just its extension.

Two media categories are recognized:

Category	What counts	Where it's attached
Image	MIME types starting with image/, except image/svg+xml and image/vnd.fastbidsheet	read embeds image/jpeg, image/png, image/gif, and image/webp as image attachments
PDF	application/pdf	read embeds it as a PDF attachment

note

Whether the model can actually consume an attachment depends on the selected model's input capabilities. If a model doesn't support a given media type, the attachment can surface as an error instead of being silently dropped.

Images are auto-resized before sending

Image attachments are normalized before they are sent to the model. If an image exceeds the configured limits, Neusis Code automatically downscales it (and, if needed, re-encodes it as JPEG at decreasing quality) until it fits — so large screenshots and photos don't get rejected for being too big.

The defaults are:

Limit	Default
Auto-resize	enabled
Maximum width	2000 px
Maximum height	2000 px
Maximum base64 payload	5242880 bytes (5 MiB)

Behavior:

• An image within all three limits is sent unchanged.
• An oversized image is downscaled (preserving aspect ratio) and re-encoded until it fits the byte and dimension limits.
• If auto-resize is turned off, an oversized image is rejected with a size error instead of being resized.
• If the image resizer can't be loaded in your environment, the original image is sent as-is rather than failing the message.

Configuration

Tune the limits under the attachment.image key in neusiscode.json (or .neusiscode/neusiscode.jsonc):

{
  "attachment": {
    "image": {
      "auto_resize": true,
      "max_width": 2000,
      "max_height": 2000,
      "max_base64_bytes": 5242880
    }
  }
}

Key	Type	Default	Description
attachment.image.auto_resize	boolean	true	Resize images before sending when they exceed the configured limits.
attachment.image.max_width	integer	2000	Maximum image width before resizing or rejecting the attachment.
attachment.image.max_height	integer	2000	Maximum image height before resizing or rejecting the attachment.
attachment.image.max_base64_bytes	integer	5242880	Maximum base64 payload bytes for an image attachment.

info

Resizing applies to images only. PDFs are passed through unchanged and are not subject to these dimension or byte limits.

PDFs in tool results (xAI / Grok and other providers)

PDFs are recognized as file attachments alongside images. When a tool result carries media and the active provider can't accept that media type inside a tool result, Neusis Code extracts the media and re-injects it as a follow-up user message, so the model still receives it instead of losing it.

This matters for xAI / Grok models (the @ai-sdk/xai provider): only images are accepted as media inside a tool result there, so a PDF returned by a tool is extracted and re-sent as a separate user-message attachment. The same extract-and-reinject path applies to other providers with partial media support — for example, Amazon Bedrock accepts images but not PDFs in tool results.

note

This page documents how attachments are processed by Neusis Code. Whether a specific model can ultimately read a PDF is governed by that model's own input capabilities.