Context References
Context references let you explicitly attach local files, folders, URLs, git
changes, or prior tool results to one Anyy turn. They are written inline in
your message with @kind:target syntax.
References are per-turn context. They do not become memory, do not edit
SOUL.md, and do not make a toolset visible. The expanded content is added as
untrusted runtime data with citation metadata.
Supported Reference Types
| Syntax | What it loads |
|---|---|
@file:path | A text file under the allowed root, or an absolute text file path when permitted by the runtime. |
@file:path:10-40 | A line range from a text file. |
@folder:path | A sorted one-level directory listing. |
@url:https://example.com/page | Public HTTP(S) page text. |
@result:tool_result_id | A stored tool result from the current session. |
@diff | Current git diff from the session working directory. |
@staged | Current staged git diff. |
@git:3 | Recent git commits with patches, clamped to at most 10. |
Usage Examples
Use @file:docs/plan.md and @diff to review the current docs changes.
Compare @file:cmd/anyy/browser.go:1-120 with @url:https://example.com/spec.
Summarize the top-level layout in @folder:internal/gateway.
The parser recognizes references when they appear at the start of text or after whitespace and common delimiters.
Line Ranges
File line ranges use the last colon in the target:
@file:internal/tools/artifact.go:1-120
The range must be start-end, both positive integers, and end must be greater
than or equal to start. Bad ranges are converted to warning references instead
of being silently ignored.
Size Limits
Default expansion limits are:
| Limit | Default |
|---|---|
| References per turn | 8 |
| Bytes per reference | 64 KiB |
| Total reference bytes | 192 KiB |
| URL content chars | 12,000 |
| Git capture bytes | 256 KiB |
After expansion, the context builder estimates token usage. If references exceed 25% of the context window, Anyy adds a warning. If they exceed 50%, Anyy refuses the expanded reference block and returns a warning reference instead.
Safety
Sensitive path blocking
Anyy blocks obvious secret paths and names before loading local file,
folder, or git reference content. Blocked examples include .ssh, .aws,
.kube, .docker, .env, .npmrc, .netrc, credentials.json, private key
names, and path segments containing credential, token, secret, api_key,
or similar markers.
Path traversal protection
Relative folder and git references are resolved against the request working
directory and allowed root. They cannot escape that root through .. or
symlinks.
File references also reject parent-path components for relative profile-home resolution and refuse symlinked or non-regular files.
Binary file detection
File references reject binary content containing NUL bytes. Large text files must be referenced with a line range or reduced before they can be attached.
URL references fetch only public HTTP(S) pages. Private/internal network URLs and unsupported schemes are blocked.
Platform Availability
Context references require the resident runtime path that provides the reference expander. They are available in gateway turns that pass user text and reference roots to prompt assembly.
If a surface does not provide a working directory or allowed root, folder, diff, staged, and git references may fail with a warning reference.
Interaction With Memory And Compression
References are not memory. If a reference contains a stable user preference, ask Anyy to save a concise fact to memory instead of relying on the reference in future turns.
Large references are budgeted before prompt assembly. When they cannot fit, Anyy attaches a warning instead of silently dropping all context.