Docs/How-to guides/Use @-mention context

Use @-mention context

Inline a file, diff, charm spec, live Juju view, indexed docs passage, or URL straight into your message — before the LLM sees it — instead of asking the agent to fetch it.

Why mention context inline

The agent has tools for reading files, running git diff, fetching URLs, and so on. When you already know what context the next reply needs, asking the agent to fetch it adds a tool round-trip (extra latency, extra tokens) that you can skip by pasting the content with a mention.

Mentions are expanded before the message is sent to the LLM. The substituted block is wrapped in a [@name]…[/@name] fence and recorded in the transcript so the intent (“the user pulled config.yaml in”) stays visible alongside the content.

Don't pre-fetch context for things the agent will discover on its own — the autonomous loop is good at that. Use mentions when (a) you've spotted the file/section that matters and want to save the round-trip, or (b) you want a cited answer rather than the agent paraphrasing from memory.

The provider catalogue

MentionSubstitutes
@file <path> Contents of a repo-relative file. Absolute paths and .. traversal are rejected.
@diff Output of git diff HEAD in the active charm.
@tree [path] Repo-tracked file listing via git ls-files. Falls back to a plain walk outside a git checkout.
@problems Current ruff / ty / charmlint diagnostics. Shares the 30-second cache used by /diagnostics.
@url <url> The fetched body of a URL, run through the same private-IP block, llms.txt probing, and HTML-to-text extraction the agent uses.
@charm <name> Charmhub metadata for the named charm: relations, config, current revision.
@preset [slug] A known-good bundle shape from the built-in catalogue. Bare lists the shapes (cos-lite, twelve-factor-cos, identity-platform, charmed-kubeflow); with a slug, the full layout — apps grouped by semantic layer, then every relation edge with its interface name and a one-line description.
@juju <subcmd> Read-only Juju subcommand output. Allowlisted: status, show-unit, show-application, show-model, config, list-secrets, show-relation, list-models.
@docs <site> <query> Top hits from your indexed Canonical documentation. Requires cantrip docs index to have run first — see Index the charm docs.
@symbol <query> Workspace symbol search across the active charm via the read-only code-intel index. Match policy: exact qualified > exact > prefix > fuzzy. Truncated matches keep an honest count instead of silently eliding.
@definition <symbol> Resolve a symbol to its defining file, line, and a bounded snippet. Ambiguous names render every candidate.
@references <symbol> Every recorded callsite for a symbol with file:line locations. Pairs naturally with @definition.

@symbol, @definition, and @references only register on sessions that have an active charm path — they share the index that powers the matching /symbols, /definition, and /references slash commands.

Each provider has a per-call character cap; over-budget output is truncated with a [truncated N chars] footer rather than silently elided.

Tab-complete in the TUI

Type @ mid-message and a popup lists every registered provider. Keep typing to filter: 

cantrip> look at @fi|
            @file
            @file <path>

Tab completes the highlighted suggestion without disturbing the surrounding prose. Up / Down moves the highlight; Esc dismisses the popup so a literal @x stays a literal @x.

Realistic examples

Pull in a config file before steering

cantrip> the existing config is @file config/app.yaml —
keep the same shape but split the database connection into its
own section.

The agent receives the file contents inline and can reason about the change without calling read_file first.

Cite indexed docs in a question

cantrip> how do I model a database relation? @docs ops relation

The top retrieved passages from the indexed ops documentation are pasted in with their canonical URLs, so the answer is grounded in cited text rather than the model's recollection of the API.

Compare a live Juju model against expectations

cantrip> the deploy looked off — here's status now: @juju status
why is the relation showing as pending?

@juju runs only the read-only allowlisted subcommand; a typo cannot reach a destructive verb.

Wire relations against a known bundle shape

cantrip> integrate the new app with COS — @preset cos-lite
which of those edges does a 12-factor app need?

@preset cos-lite pastes in the canonical COS Lite layout — apps by layer, then every relation edge with its interface name and a one-line description — so the agent composes the relations from the agreed shape instead of re-deriving it from web docs. Bare @preset lists the available shapes.

Forward a remote document for review

cantrip> here's the spec the team agreed on:
@url https://internal.example.com/specs/charm.html
does our current design match?

Mentions inside slash commands

Slash commands run before mention expansion, so a literal @x inside a slash argument is not substituted: 

cantrip> /remember user wants @-mentions tested before merging

The memory captures the literal text including the @. Combined with user-defined slash commands, this means a custom command's argument text is itself a clean string — mention expansion only fires on the raw chat input.

Add your own provider

The mention catalogue is extensible:

The protocol and registration shape are documented in design/CONTEXT_PROVIDERS.md.

Caveats