CodeAttachments

Attachments

Bahulam can accept images, PDFs, and text documents directly in your prompt — plus grab the current OS clipboard on macOS and Windows. Everything is resolved client-side and inlined into the turn the model sees. No backend upload for text-first formats.

Attach a file — @path

Anywhere in your prompt, write @ followed by a file path. Bahulam resolves the path (relative to cwd, or ~/... for home-relative) and attaches its contents.

what's wrong with @src/routes/user.ts and @docs/spec.md?

The referenced files are inlined into the user turn. The agent sees them before its first tool call — no read_file needed.

Supported types

Images (base64-encoded in the LLM message; per-image cap 8 MB, per-turn cap 20 MB):

  • .png, .jpg, .jpeg, .webp, .gif

Documents (text-extracted client-side and inlined; per-doc cap 80,000 characters, per-turn cap 200,000 characters, per-file byte cap 5 MB):

  • .pdf (via pdf-parse)
  • .txt, .md, .mdx, .rst
  • .csv, .tsv, .log
  • .json, .yaml, .yml, .toml, .ini, .env
  • .html, .htm, .xml

Anything else — the CLI falls back to the read_attachment tool, which the agent invokes on-demand (.docx, other office formats, unknown types).

Caps and overrides

Env vars (integer bytes/chars):

VarDefaultWhat it caps
BAHULAM_MAX_IMAGE_BYTES8 * 1024 * 1024Per-image size
BAHULAM_MAX_TURN_BYTES20 * 1024 * 1024Total image bytes per turn
BAHULAM_MAX_DOC_CHARS80_000Per-document extracted char count
BAHULAM_MAX_TURN_DOC_CHARS200_000Total document char count per turn
BAHULAM_MAX_DOC_BYTES5 * 1024 * 1024Per-document raw byte size

Clipboard — @clipboard or @paste

Grabs the OS clipboard (macOS / Windows). If the clipboard holds an image, it attaches as an image. If it holds text, it inlines as text.

here's the error @paste — trace it

Under the hood: pbpaste on macOS, PowerShell’s Get-Clipboard on Windows. Linux clipboard support is best-effort (relies on xclip / wl-paste).

Slash commands

For images you want to attach without embedding a path in prose:

CommandWhat it does
/attach <path>Queue an image for the next prompt
/attach clipboardGrab the current clipboard image
/attachmentsList queued attachments
/attachments clearClear the queue

Queued attachments are consumed by the next prompt; they don’t persist across turns.

What the agent sees

For images: an OpenAI-compatible image_url (base64 data URL) content block. The vision-capable model (Sonnet / GPT-4o / etc.) sees it directly.

For documents: a fenced text block prefixed with the source path, e.g.

Attachment: docs/spec.md

  # Product spec
  ...

For clipboard text: same, with source [clipboard].

Tips

  • Explicit is cheap — writing @file.md costs nothing extra vs the agent having to call read_file. Prefer @ for files you know are relevant.
  • Line ranges? Not yet — @file.py:100-200 isn’t supported. Attach the whole file (if under the cap) or point the agent at the range in prose.
  • Screenshots: pbcopy a screenshot on macOS (Shift-Cmd-Ctrl-4) then reference @clipboard in your prompt — one gesture, no temp file.
  • Big PDF? If it exceeds the 80K-char cap it truncates. Ask the agent to read specific sections with read_attachment.
SkillsAutomation & CI/CD