Research workflow

Understand unfamiliar code without handing over the whole repository.

Instead of pasting files into your main agent's context, delegate a focused question: triss ask reads only the sources you name, sends them to your selected provider, and returns findings with source references you can verify yourself.

Use it when

You need an answer to a specific question about selected sources before you start changing them — how a mechanism works, where a decision is made, what a module enforces. The question is bounded, and so is the corpus: you choose exactly which files Triss reads.

Provide

A precise question. Ask for the specific behavior, precedence, or constraint you need, and ask for cited lines.
The selected files or globs. Quote globs so your shell passes them through to Triss instead of expanding them:

triss ask --paths "src/**/*.js" --question "Where is request validation handled, and what does it enforce? Cite the relevant lines."

Do not include secret files such as .env in the corpus — what you select is what gets sent to your model provider. Directories are not an automatic recursive corpus: pass files or a glob such assrc/**/*.js.

Run

The command below is the recorded run shown later on this page. It was executed with triss ask --provider zai against a source file of the Triss repository itself, at a public commit.

triss ask --provider zai --paths src/model-selection.js --question "How are provider, model, and execution engine selected? Cite the relevant lines and distinguish explicit request values from configured defaults."

This is an example recorded on Triss' own sources. In your own repository you choose your own paths and your own question — no project needs to contain src/model-selection.js. Use your configured provider by omitting --provider, or pass the provider you selected.

Inspect

Open the cited files and lines and compare them with each claim.
Identify what remains unknown: a focused answer about selected files is not a map of the whole repository.
Keep the details your main agent needs — verified behavior, exact identifiers, line references — and drop the rest.

Recorded example

Recorded 2026-09-05 · Triss 0.42.0 · provider zai · model zai/glm-5-turbo · engine opencode

The command below was run against src/model-selection.js at commit3208b6d of the public repository. Every excerpt on this page was manually checked against that source before publishing.

Command

triss ask --provider zai --paths src/model-selection.js --question "How are provider, model, and execution engine selected? Cite the relevant lines and distinguish explicit request values from configured defaults."

Excerpt from a recorded run — three of the answer's findings

Explicit — provider field: otherwise `validated.provider` (from `request.provider`) is used (line 51). … Configured default: if neither is set, `snapshot.defaultProvider.value` is canonicalized via `assertCanonicalProviderId` (lines 47–50) and used (line 51).
View src/model-selection.js lines 44–52 on GitHub
Verification: Checked against the cited commit: line 51 resolves `modelProvider || validated.provider || defaultProvider`, and lines 65–69 record the same three provenance tiers.
Explicit: if `validated.model` exists, `nativeModel = validated.model.nativeModel`, provenance `{ source: 'explicit' }` (lines 56–58). … Configured default: otherwise the atom `profile[role]` is taken from the provider profile and parsed by `parseConfiguredModel` (lines 60–62).
View src/model-selection.js lines 54–62 on GitHub
Verification: Checked the explicit branch (lines 56–58) and the configured-role branch (lines 60–62), including the parseConfiguredModel guards at lines 25–37.
Explicit request: `validated.engine` (line 78). Command default: `request.defaultEngine`, validated by `assertModelExecutionEngine` (lines 75–77) … Configured default: `snapshot.defaultEngine.value`; if the snapshot has none, registry fallback `DEFAULT_MODEL_ENGINE` with provenance source `'registry-default'` (lines 70–74).
View src/model-selection.js lines 70–83 on GitHub
Verification: Checked the engine chain `validated.engine || commandDefaultEngine || configuredEngine` at lines 78–83 and the registry fallback at lines 70–74.

Limits of this example

Single-file corpus: the run read one source file. The findings describe the provided context, not the whole repository.
Executed through the configured default engine (opencode, one-shot read-only projection) with provider zai and model glm-5-turbo. Other providers, models, or engines may answer differently.
Line numbers refer to commit 3208b6d and can drift as the file changes.
A recorded answer is evidence for this corpus and question, not a guarantee of general correctness.

Bring it back

When the findings have been verified, hand them to your main agent as context for the change you are about to make:

Example instruction

"Use these verified findings to plan the change. Re-open the relevant source before editing."

This is an example instruction you write yourself — not command output, and not a recorded result.

Limits

The answer analyzes the context you passed. It is not proof that the whole repository is understood.
The model can be wrong, even when it cites real lines.
A follow-up query may be needed: narrower files, or a more specific question.