Searching Past Sessions and Agent Transcripts
thrum transcript searches and reads the agent session transcripts on THIS box only. It talks to the local daemon;
there is no cross-peer search. It is a Pro feature.
Workflow
- Count first:
thrum transcript search --count <query>. It prints a total and, while the count is exact, matches per agent, with no snippets. - Narrow with
--agent,--worktree,--since,--until,--runtimeor--in. - Search with a small limit:
thrum transcript search --limit 5 <query>. - Read one or two windows only:
thrum transcript show <runtime>:<session>:<seq>. - For a broad question, use the
history-searchskill: a cheap sub-agent runs steps 1-4 and returns a short cited answer. Never paste raw transcript text back into your own context.
Each hit prints as agent · YYYY-MM-DD · runtime:session:seq · snippet. Pass the runtime:session:seq to show.
Scope
- With no scope flag the search covers your own agent.
--agent a,bsearches those agents.--worktree w1,w2searches sessions in those worktrees.--allsearches every agent on this box. The three are mutually exclusive.- When several agents share one worktree, each session is attributed to only one of them.
--worktreefinds all of those sessions;--agentmay miss some. Use--worktreewhen an expected session does not appear. --sinceand--untiltake7d,24h, an RFC3339 time orYYYY-MM-DD(UTC;--untilcovers the whole day).--runtime claude(orcodex, and so on) keeps one runtime.--in proseor--in codekeeps only prose or only fenced code.--by sessiongroups results by session.--limitdefaults to 5; the maximum is 50.--jsonprints the full response and lifts the 8 KiB output cap.
Query syntax
| You type | It means |
|---|---|
deploy rollback |
both words must appear (AND) |
"exact phrase" |
the exact words, no stemming |
-word or -"a phrase" |
exclude matches containing it |
a OR b |
either word; a OR b c means (a or b) and c |
migrat* |
any word starting with migrat; needs at least 2 characters before the * |
- Unquoted prose words are stemmed:
deployingalso findsdeployed. Quote a word to match it exactly. - Text from
--in codeis matched exactly, without stemming. - A query is limited to 50 terms.
- A query starting with
-needs--first:thrum transcript search -- -flaky timeout. - A query needs at least one positive term; a query of only exclusions is refused.
Show
thrum transcript show <runtime>:<session>:<seq> prints the entries around one hit; the hit itself is marked with
>. Defaults are 3 entries before, 3 after and 4000 bytes of text. --before and --after go up to 10 and
--max-bytes up to 16000. Larger values are clamped.
Reading the output
N of TOTALis the number of hits shown out of all matches. A broad search (--all) counts exactly up to 1000 matches and then reads1000+, meaning at least that many; no per-agent counts are printed then.(output capped at 8 KiB)means some hits were dropped from the end; lower--limitor narrow the query.(partial: index catching up...)means the index is still catching up with new transcripts, so results may be incomplete. Retry later for a complete answer.(many matches: newest first; add words to rank by relevance)means the query is too broad to rank, so hits are listed newest first. Add words, quotes or filters.session was pruned by retentionmeans that session's transcript is gone.
Unavailable and refused
Transcript search requires a license: not entitled for this machine. Run 'thrum license activate' to enable it.Tell the user. Do not retry.transcript search: transcript search index not available(reindex saystranscript reindex: ...) ortranscript store unavailablemeans the daemon is still starting, transcripts are disabled (transcripts.enabledis false), or the search index could not be opened. There is no fallback search. Tell the user; do not retry in a loop.
Reindex
thrum transcript reindex rebuilds the search index in the background. It is rarely needed; searches report
partial until it finishes.