Vrefer

vrefer

vrefer prints the conversation of another vlx-term session. The target session does not have to be running, and nothing is sent to it — this only reads what it already recorded.

When to use it

Reach for this the moment a request depends on what another conversation contains:

• The user names a session, by title or by id.
• The user refers to another conversation without naming it: "that other session", "last time", "the other branch", "we already decided this somewhere".
• vsearch returned a hit and you need the conversation around the snippet.

These come in whatever language the user speaks; the trigger is the meaning, not the wording.

The failure to avoid: answering "I have no access to other sessions" or asking the user to paste the content over. That is wrong here — you do have access, and this is how. If you are unsure which session they mean, run vrefer --list or vsearch and ask, rather than declining.

Search first, then refer. When the target is not named outright, run vsearch and let it hand you the id instead of paging through vrefer --list.

How to run it

vrefer <session> [--last N] [--range A:B] [--json]
vrefer <session> --ask "<question>" [--with KIND] [--timeout SECONDS]
vrefer --list

<session> accepts, in this order: a full session id, an id prefix of at least 8 characters, an exact session name, or a unique substring of a name. Quote names containing spaces. Prefer the id that vsearch printed — names can be ambiguous.

You get the whole conversation

vrefer <session> returns the entire transcript. Referencing another session means wanting what it says, and a partial record read as a whole one leads to confident wrong conclusions.

Narrow it only when you actually want less:

• --last N gives just the last N messages, for when you only need to know where that session got to.
• --range A:B gives an exact slice by message index, zero-based, A included and B excluded. The msg N anchors in vsearch output are these indices, so --range 40:60 reads around a hit at message 50.

When you only need one thing from a long conversation

--ask puts the reading somewhere else. A short-lived answering agent gets the session context and your question, and only its answer comes back — the transcript never enters your context.

vrefer 2feead2c --ask "how did the throttling design end up, and why"

Use it when the target is long and you know what you are after. Read the transcript directly when it is short, or when you need its actual wording rather than someone's reading of it. A one-line lookup does not justify starting an agent: that run costs the user real tokens and takes tens of seconds.

The default context mode is Full transcript, preserving the original behavior: the answering agent reads the complete transcript directly. The user can instead enable Summarize first in Settings → Behavior → Session reference context and choose one global summary Agent, model, and reasoning effort. In that mode VelaTerm first compresses the transcript with exactly that selection, searches the same session for terms relevant to the question, then gives the answering agent both the summary and original search excerpts. Do not guess which mode is enabled; the attribution line reports it.

Summaries are generated for each question and are not cached. Summarizing reduces the final answering agent's context, but processing the full transcript first may increase total time and token usage.

The reply opens with a line naming which agent answered, how many messages were covered, and whether the context was full or summarized. Quote it as that agent's reading of another session, not as that session's own words.