Context References

Type@followed by a reference to inject content directly into your message. Hermes expands the reference inline and appends the content under an— Attached Context —section.

@ --- Attached Context ---

Supported References​

Syntax Description
@file:path/to/file.py Inject file contents
@file:path/to/file.py:10-25 Inject specific line range (1-indexed, inclusive)
@folder:path/to/dir Inject directory tree listing with file metadata
@diff Injectgit diff(unstaged working tree changes)
@staged Injectgit diff –staged(staged changes)
@git:5 Inject last N commits with patches (max 10)
@url:https://example.com Fetch and inject web page content

@file:path/to/file.py @file:path/to/file.py:10-25 @folder:path/to/dir @diff git diff @staged git diff --staged @git:5 @url:https://example.com

Usage Examples​

Review @file:src/main.py and suggest improvementsWhat changed? @diffCompare @file:old_config.yaml and @file:new_config.yamlWhat's in @folder:src/components?Summarize this article @url:https://arxiv.org/abs/2301.00001

Multiple references work in a single message:

Check @file:main.py, and also @file:test.py.

Trailing punctuation (,,.,;,!,?) is automatically stripped from reference values.

, . ; ! ?

CLI Tab Completion​

In the interactive CLI, typing@triggers autocomplete:

@

@ @diff @staged @file: @folder: @git: @url: @file: @folder: @

Line Ranges​

The@file:reference supports line ranges for precise content injection:

@file:

@file:src/main.py:42        # Single line 42@file:src/main.py:10-25     # Lines 10 through 25 (inclusive)

Lines are 1-indexed. Invalid ranges are silently ignored (full file is returned).

Size Limits​

Context references are bounded to prevent overwhelming the model’s context window:

Threshold Value Behavior
Soft limit 25% of context length Warning appended, expansion proceeds
Hard limit 50% of context length Expansion refused, original message returned unchanged
Folder entries 200 files max Excess entries replaced with- …
Git commits 10 max @git:Nclamped to range [1, 10]

- ... @git:N

Security​

Sensitive Path Blocking​

These paths are always blocked from@file:references to prevent credential exposure:

@file:

~/.ssh/id_rsa ~/.ssh/id_ed25519 ~/.ssh/authorized_keys ~/.ssh/config ~/.bashrc ~/.zshrc ~/.profile ~/.bash_profile ~/.zprofile ~/.netrc ~/.pgpass ~/.npmrc ~/.pypirc $HERMES_HOME/.env

These directories are fully blocked (any file inside):

~/.ssh/ ~/.aws/ ~/.gnupg/ ~/.kube/ $HERMES_HOME/skills/.hub/

Path Traversal Protection​

All paths are resolved relative to the working directory. References that resolve outside the allowed workspace root are rejected.

Binary File Detection​

Binary files are detected via MIME type and null-byte scanning. Known text extensions (.py,.md,.json,.yaml,.toml,.js,.ts, etc.) bypass MIME-based detection. Binary files are rejected with a warning.

.py .md .json .yaml .toml .js .ts

Platform Availability​

Context references are primarily aCLI feature. They work in the interactive CLI where@triggers tab completion and references are expanded before the message is sent to the agent.

@

Inmessaging platforms(Telegram, Discord, etc.), the@syntax is not expanded by the gateway — messages are passed through as-is. The agent itself can still reference files via theread_file,search_files, andweb_extracttools.

@ read_file search_files web_extract

Interaction with Context Compression​

When conversation context is compressed, the expanded reference content is included in the compression summary. This means:

@file: @file:main.py:100-200

Common Patterns​

# Code review workflowReview @diff and check for security issues# Debug with contextThis test is failing. Here's the test @file:tests/test_auth.pyand the implementation @file:src/auth.py:50-80# Project explorationWhat does this project do? @folder:src @file:README.md# ResearchCompare the approaches in @url:https://arxiv.org/abs/2301.00001and @url:https://arxiv.org/abs/2301.00002

Error Handling​

Invalid references produce inline warnings rather than failures:

Condition Behavior
File not found Warning: “file not found”
Binary file Warning: “binary files are not supported”
Folder not found Warning: “folder not found”
Git command fails Warning with git stderr
URL returns no content Warning: “no content extracted”
Sensitive path Warning: “path is a sensitive credential file”
Path outside workspace Warning: “path is outside the allowed workspace”