Context References: @ Syntax for Inline Context Injection
- Use all seven @ syntax forms: @file, @file with line ranges, @folder, @diff, @staged, @git:N, and @url
- Combine context references naturally inside ordinary message text
- Know the soft (25%) and hard (50%) context-budget limits and what happens at each
- Identify which paths are always blocked from @file: references for security reasons
- Recognize that @ syntax is CLI-only and does not expand on messaging platforms
Why This Exists Alongside Tools
Your agent can already read files and check git status using its terminal and file tools -- you saw that in Lesson 3. Context references are a shortcut on top of that: instead of asking the agent to go look something up, you can inject it directly into your message using @ syntax, and Hermes expands the reference inline before the agent even starts thinking about your request. It is the difference between asking someone to go find a document and just handing it to them.
The Full Syntax Table
@file:path/to/file.py@file:path/to/file.py:10-25@folder:path/to/dir@diff@staged@git:5@url:https://example.comUsing It in Practice
These can be combined naturally inside an ordinary sentence -- you do not need any special framing:
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 @url:https://arxiv.org/abs/2301.00001
One small convenience: trailing punctuation right after a reference -- a comma, period, semicolon, exclamation point, or question mark -- is automatically stripped, so @diff? at the end of a question still resolves correctly rather than trying to match a file literally named "diff?".
Line Ranges
For pointing at something precise inside a large file, use the line-range form: @file:src/main.py:42 for a single line, or @file:src/main.py:10-25 for a range. This is the fastest way to ask a focused question about one function without pulling in an entire file the agent then has to search through itself.
Limits Worth Knowing
- A soft limit kicks in at 25% of your context window -- you get a warning, but the expansion still happens.
- A hard limit at 50% of context refuses the expansion outright -- this is what stops one giant
@folder:reference from silently consuming your entire conversation budget. @folder:entries cap out at 200 files displayed.@git:commit counts are clamped to 10 maximum, even if you ask for more.
Security: Some Paths Are Always Blocked
Context references cannot be used to read credential or key material, regardless of what you type. Blocked locations include ~/.ssh/, ~/.aws/, ~/.gnupg/, and ~/.kube/. Path traversal attempts and binary files are also detected and handled, so @file: cannot be used to smuggle in something outside what it is meant for.
Where This Does and Does Not Work
Context references are an interactive CLI feature, with tab completion to help you find the right path as you type. If you are using a messaging platform integration (covered in Hermes Agent Advanced), @ syntax does not get expanded there -- the agent can still access files and git state through its regular tools, just not via this particular shortcut.
When to Reach for This vs. Just Asking
A reasonable rule of thumb: if you already know exactly which file, line range, or diff is relevant, use @ syntax and save the agent a search step. If you are not sure where the relevant code lives, just describe what you want and let the agent use its tools to go find it -- that is what Lesson 3's "tools work out of the box" lesson was about. The two approaches are complementary, not competing.
The next lesson covers the last piece of the foundational picture: teaching your agent to actually remember things across sessions, not just within one conversation.
- @file:path:10-25 line ranges are the fastest way to point at something precise without pulling in an entire file
- The hard limit (50% of context) refuses expansion outright -- this is what prevents one oversized @folder: reference from consuming your whole conversation budget
- Credential paths (~/.ssh/, ~/.aws/, ~/.gnupg/, ~/.kube/) are always blocked from @file: regardless of what you type
- @ syntax works in the interactive CLI with tab completion, but does not expand on messaging platform integrations
- Use @ syntax when you already know exactly what is relevant; let the agent use its own tools to search when you do not -- the two are complementary