File Reference Middleware
Clutch automatically detects file paths in your chat messages, reads the files, and injects their contents into the LLM context. No drag-and-drop, no file browser, no copy-paste — just type the path and send.
How It Works
When you type a message like:
Can you review ~/Documents/report.md for me?
Clutch detects ~/Documents/report.md, reads the file, and appends its contents to your message before sending it to the API. The LLM sees both your message and the file content — as if you had pasted it yourself.
Path Patterns
Clutch recognizes three path formats directly in chat messages:
| Pattern | Example | Resolves to |
|---|---|---|
| Tilde path | ~/Downloads/report.md | $HOME/Downloads/report.md |
| Absolute path | /Users/you/src/main.rs | Direct file read if within allowed directories |
| Relative path | ./src/lib.rs | Resolved against active workspace directory |
Injection Format
Detected files are wrapped in a structured tag before reaching the LLM:
[File: ~/Downloads/report.md]
(contents of the file here)
---
User message: Can you review ~/Downloads/report.md for me?Security Sandbox
File access is strictly scoped to prevent reading sensitive system files or credentials.
| Allowed | Blocked |
|---|---|
| Active workspace directory | ~/.ssh/ — SSH keys |
~/Downloads/ |
~/.aws/ — AWS credentials |
~/Desktop/ |
~/.gnupg/ — GPG keys |
~/Documents/ |
/etc/, /var/ — system directories |
~/ home directory files |
Path traversal (../) — any path navigating up |
Edge Cases
| Scenario | Behavior |
|---|---|
| File not found | [File ~/Downloads/missing.txt not found] appended to message |
| File larger than 1 MB | First 500 lines injected, [...truncated at 500 lines] appended |
| Binary file | [~/Downloads/photo.png is a binary file — skipped] |
| Path outside sandbox | [Path /etc/passwd is outside allowed directories — blocked] |
| Tilde with no HOME | [Could not resolve ~ — no home directory] |
| Multiple files in one message | All detected files are read and injected, separated |
URL paths (https://...) | Not treated as file references — processed by web fetcher instead |
Integration with Workspaces
Relative paths like ./src/main.rs or ../lib/helper.rs are resolved against your active workspace directory (set in Settings → Workspaces). This makes file references work naturally within your project structure. If no workspace is active, relative paths resolve against the current working directory.
Rust Backend & Performance
File detection and reading happens entirely in the Rust backend before the API call is made. This means:
- Zero overhead on the frontend — no blocking reads in the UI thread
- Security checks run server-side, not in the renderer process
- Large files are capped at 1 MB to prevent excessive token consumption
- Binary files are detected by null byte scanning (fast, no MIME detection needed)
Using with Slash Commands
The File Reference Middleware works alongside slash commands. You can mix both freely — type a slack command for an action, and include a file path in the same message for context:
/read src/main.rsFor programmatic file reading from slash commands, use /read (reads a single file) or /ls (lists a directory). These work the same way as typing a path directly.