ebcb81b649
New documentation for features that existed in code but had no docs:
New page:
- context-references.md: Full docs for @-syntax inline context
injection (@file:, @folder:, @diff, @staged, @git:, @url:) with
line ranges, CLI autocomplete, size limits, sensitive path blocking,
and error handling
configuration.md additions:
- Environment variable substitution: ${VAR_NAME} syntax in config.yaml
with expansion, fallback, and multi-reference support
- Gateway streaming: Progressive token delivery on messaging platforms
via message editing (StreamingConfig: enabled, transport, edit_interval,
buffer_threshold, cursor) with platform support matrix
- Web search backends: Three providers (Firecrawl, Parallel, Tavily)
with web.backend config key, capability matrix, auto-detection from
API keys, self-hosted Firecrawl, and Parallel search modes
security.md additions:
- SSRF protection: Always-on URL validation blocking private networks,
loopback, link-local, CGNAT, cloud metadata hostnames, with
fail-closed DNS and redirect chain re-validation
- Tirith pre-exec security scanning: Content-level command scanning
for homograph URLs, pipe-to-interpreter, terminal injection with
auto-install, SHA-256/cosign verification, config options, and
fail-open/fail-closed modes
sessions.md addition:
- Auto-generated session titles: Background LLM-powered title
generation after first exchange
creating-skills.md additions:
- Conditional skill activation: requires_toolsets, requires_tools,
fallback_for_toolsets, fallback_for_tools frontmatter fields with
matching logic and use cases
- Environment variable requirements: required_environment_variables
frontmatter for automatic env passthrough to sandboxed execution,
plus terminal.env_passthrough user config
3.9 KiB
sidebar_position, title, description
| sidebar_position | title | description |
|---|---|---|
| 9 | Context References | Inline @-syntax for attaching files, folders, git diffs, and URLs directly into your messages |
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.
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 |
Inject git diff (unstaged working tree changes) |
@staged |
Inject git diff --staged (staged changes) |
@git:5 |
Inject last N commits with patches (max 10) |
@url:https://example.com |
Fetch and inject web page content |
Usage Examples
Review @file:src/main.py and suggest improvements
What changed? @diff
Compare @file:old_config.yaml and @file:new_config.yaml
What'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:
@shows all reference types (@diff,@staged,@file:,@folder:,@git:,@url:)@file:and@folder:trigger filesystem path completion with file size metadata- Bare
@followed by partial text shows matching files and folders from the current directory
Line Ranges
The @file: reference supports line ranges for precise content injection:
@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:N clamped to range [1, 10] |
Security
Sensitive Path Blocking
These paths are always blocked from @file: references to prevent credential exposure:
- SSH keys and config:
~/.ssh/id_rsa,~/.ssh/id_ed25519,~/.ssh/authorized_keys,~/.ssh/config - Shell profiles:
~/.bashrc,~/.zshrc,~/.profile,~/.bash_profile,~/.zprofile - Credential files:
~/.netrc,~/.pgpass,~/.npmrc,~/.pypirc - Hermes env:
$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.
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" |