Add context

Use @ references in an Orek prompt to choose the files, line ranges, or symbols Orek should read for your request. Orek reads them before sending the request to your model and can add related code through automatic retrieval.

@ references need index.enabled = true (the default). File references read directly from your project folder even before you build the index; @SymbolName references and automatic retrieval need a built index. Replace the example paths and symbol names below with ones from your project.

Type @ in the composer and choose a completion, or type the reference yourself. Ctrl+J inserts a newline while composing. See Using Orek.

What you want to include	Prompt syntax
A file	`@path/to/file`
A line range	`@path/to/file:120-180`
A symbol definition	`@SymbolName`
A literal `@` character	`@@`
No automatic retrieval for this request	`@!retrieve` followed by your prompt

For example, select lines before asking about their behavior:

In Orek · prompt

@src/auth.ts:120-180

Explain how this code handles an expired session. Identify the condition
that sends the user back to the login page.

After building the index, select a symbol definition:

In Orek · prompt

@parse_config

Explain what this function accepts and what happens when a required value
is missing.

You can also select starting points and let automatic retrieval find related code, up to the space set aside for context:

In Orek · prompt

@src/auth.ts
@src/session.ts

Trace how login creates a session and how later requests validate it.

Reference grammar

Token	Meaning	Example
`@path/to/file`	Include file content.	`@src/main.rs`
`@path\to\file`	Include a file using Windows separators.	`@src\main.rs`
`@path/to/file:start-end`	Include a 1-indexed, inclusive line range.	`@src/main.rs:40-100`
`@SymbolName`	Include a symbol’s definition when its name has one match in the index.	`@AuthService`
`@!retrieve`	Skip automatic retrieval for this turn.	`@!retrieve explain Rust ownership`
`@@`	Emit a literal `@`.	`email @@user`
`@path/to/dir/`	Name a directory without including its files.	`@src/`

File references

In Orek · prompt

@Cargo.toml show me the dependencies
@src/lib.rs:1-50 what does this module export?
@tests/test_foo.rs:100-120 diagnose this failing test
@src\main.rs:40-100 explain this range

Relative paths resolve from the project root. Both / and \ work, including absolute Windows drive and UNC forms. Line numbers are 1-indexed and inclusive.

Explicit file content rejects binaries and files larger than 512 KiB. This limit is separate from index.max_file_bytes, whose default indexing limit is 1 MiB per file. See index configuration.

Symbol references

In interactive chat, build and check the index (or run orek index build and orek index status in your shell):

In Orek · command

/index build

In Orek · command

/index status

Then use a symbol in a prompt:

In Orek · prompt

@AuthService explain how token refresh works
@TokenStore what does this trait require?

Orek looks the symbol up in the code index. A unique match includes the lines of its definition. See Find and explore code for structural queries.

Directory references

@src/ does not include the files in a directory or limit retrieval to that directory. Reference specific files (@src/lib.rs), or ask Orek to search the directory.

Escaping

Type @@ when the prompt needs a literal @:

In Orek · prompt

email @@dave about the bug

Directives

`@!retrieve`

Skip automatic retrieval for one turn while keeping your @ references:

In Orek · prompt

@!retrieve @src/lib.rs:1-50 explain only this excerpt

For a general question, the directive can reduce unrelated project context:

In Orek · prompt

@!retrieve what is the difference between Box and Rc in Rust?

This does not clear earlier conversation context, ignore your @ references, or stop the agent from using tools later in the turn.

Automatic retrieval also depends on index.retrieval.enabled. In the TUI, /retrieval off overrides it for the session and /retrieval clear restores the configured value. /retrieval persist off saves it as your user default. These switches do not stop indexing, @ references, or code graph queries. See retrieval controls.

Inspect resolution

Inside interactive chat, run:

In Orek · command

/context

In Orek · command

/context raw

These show the latest turn’s included files, line counts, token use, retrieval ranks, and any references left out, with the reason. If you set observe.otlp_endpoint, Orek also sends context counts with each turn’s trace. See Troubleshooting & diagnostics.

When a reference cannot be included

Condition	What happens	What to do
Missing path or path outside the project root	The reference is omitted	Select an existing file within the project
Explicit file exceeds 512 KiB	The reference is omitted	Choose a smaller file; this limit is separate from the default 1 MiB indexing limit
Binary file	The reference is omitted	Use a supported text file
Line range extends beyond the file	An end line past the end of the file is shortened to the last line; a start line past the end omits the reference	Check the current line numbers
Start line is greater than end line	The reference is omitted	Reverse or correct the range
Sensitive path, such as a key file	Orek can block the reference	Use a non-secret example or another permitted source
Missing or ambiguous symbol	The reference is omitted; an ambiguous symbol has an `ambiguous` reason	Check the index and use a file and line range to disambiguate

Keep the index current with orek index build --watch in a separate terminal, or with /index watch start inside chat. Find and explore code explains keeping the index up to date and repairing it.