Conversations¶
New to tclaude?
Start with the tutorial Keep agents going.
A conversation is the durable transcript behind a session, plus tclaude's index entry for it. Sessions are live tmux processes; conversations persist in each harness's own store and outlive the session that produced them. A session row can exit while its conversation stays listed, searchable, and resumable.
tclaude conv is one merged index across all six agent harnesses: listings load
Claude Code's cwd-indexed .jsonl store and merge in conversations from
every other registered harness — Codex, OpenCode, Copilot, Gemini, and pi —
read-only,
each entry tagged with its harness. Resume and watch-mode launch use the
recorded harness automatically.
Listing, search, resume, and archive are harness-agnostic. The physical
transcript operations — delete, prune-empty, cp, mv — and the
semantic index operate on Claude Code's store only; those sections say so.
The conversation record is independent of tmux process history: pruning an
exited row from session ls does not touch the conversation, its recorded
harness, or its resume provenance. Listing, search, archive, and resume also
work for conversations that were never enrolled as agents.
Listing¶
tclaude conv ls # conversations for the current project
tclaude conv ls -g # all projects
tclaude conv ls -n 10 # limit
tclaude conv ls --since 7d # time filter
tclaude conv ls -w # interactive watch mode
Useful flags: -l/--long, -j/--json, -c/--count, -s/--sort-by
created|modified|messages|prompt|project with -a/--asc, --since and
-b/--before (durations like 1h30m/7d or dates), -r/--reindex to force
a rescan of transcript files, and --show-archived to include conversations
hidden by tclaude archival (plus Codex conversations archived in Codex's own
native store).
tclaude conv watch is a shortcut for conv ls -w; in watch form only
-g, --since, and --before apply.
Conversations are indexed per project directory, so a plain conv ls in a
repo shows that repo's history — including a worktree's own history when run
inside the worktree — and -g widens to everything tclaude knows about.
Searching¶
tclaude conv search "authentication" # title/prompt search
tclaude conv search -g --since 24h "bug fix" # global, time-filtered
tclaude conv search --content "exact error" # full transcript search
Title-and-first-prompt search is the default. --content also reads the
transcript files themselves — slower, and cold Codex rollouts stored as
compressed .jsonl.zst are not decompressed, so those are matched on
metadata only. Other flags: -C/--context for surrounding lines,
-s/--case-sensitive, --sort-by … matches, plus the usual -g, -l,
-n, -j, -c, and time filters.
Resuming¶
The argument can also be the name or agent ID from tclaude agent ls.
conv resume finds the conversation in any harness's store, changes to its
project directory, and relaunches it through its recorded harness in a
new tmux session — you never tell it which CLI to use. The relaunch also
carries the conversation's recorded launch posture; see
Sessions.
For an agent's conversation, conv resume and watch mode first ask agentd to
prepare the agent's sandbox the way an ordinary resume does. That means the
sandbox profiles are re-read, the group's current environment and
remote-control policy apply, and the relaunch policy is followed. Only the operator can ask for this. If agentd
cannot prepare the sandbox, the conversation still resumes, under the sandbox
policy stored at its last launch, with a one-line warning saying what to do.
That happens when agentd is not running, when it cannot confirm the terminal
as the operator (export TCLAUDE_HUMAN_TOKEN), or when it is older than this
build (restart it). A refusal from agentd, such as a sandbox profile that can
no longer be applied, stops the resume, as it stops an ordinary resume.
The lower-level equivalent is tclaude session new --resume <id>, which
needs --harness for non-Claude conversations.
One gate: a conversation whose live agent is driven through Copilot's API
drive is refused a plain relaunch; pass -s/--send-keys to explicitly
proceed with a tmux send-keys launch instead.
Archiving¶
Archiving works for any indexed conversation, whatever its harness. It
stamps archived_at in tclaude's SQLite conversation index; the transcript
on disk is untouched and the operation is fully reversible. Archived
conversations are hidden from conv ls unless --show-archived.
Reincarnation archives the predecessor conversation through the same
mechanism.
Codex additionally has its own native archive state; tclaude surfaces it via
--show-archived but never modifies it.
Claude Code transcript operations¶
These commands manipulate transcript files in Claude Code's cwd-indexed store. They do not touch Codex, OpenCode, Copilot, Gemini, or pi stores.
conv delete¶
tclaude conv delete <conv-id> # with confirmation
tclaude conv delete -y -g <id> # skip confirmation, search globally
Deletes the transcript, including any resumed "generations" of the same conversation.
conv prune-empty¶
Deletes conversations with no user messages, stale index entries, and dangling companion directories (subagent transcripts).
conv cp / conv mv¶
Copies or moves a transcript to another real project path so it lists (and
resumes) there. cp assigns the copy a new UUID. -f overwrites, -g
searches globally.
Watch mode¶
tclaude conv watch (or conv ls -w) is an interactive picker over the
merged conversation list:

Conversation watch across all projects and harnesses
| Key | Action |
|---|---|
↑/↓, j/k, PgUp/PgDn, g/G |
Navigate |
Enter |
Create or attach a session for the selected conversation |
/ |
Text search: title, first prompt, project path, git branch, session id |
s |
Semantic search (requires Ollama) |
Del/Backspace/ctrl+d |
Delete (session-aware confirmation, below) |
x |
Show or hide archived conversations |
w/W |
Create a worktree from the selected conversation |
f |
Group filter |
c |
Choose columns |
r |
Refresh |
h/? |
Help |
q |
Quit |
Session indicators in the list: ⚡ means the conversation has an attached
session, ▷ a detached tmux session, and ◉ a session outside tmux.
Deleting a conversation that has an active session asks what to do: y
deletes the conversation and stops the session, s stops the session only,
n cancels.
For a Claude Code entry, delete removes the transcript file itself. For an entry from any other harness, it removes only tclaude's index rows — the conversation disappears from the merged list, but the harness's own transcript store is untouched.
Semantic search¶
Semantic search ranks conversations by meaning rather than exact text, using
local Ollama embeddings. The default model is qwen3-embedding:0.6b
(nomic-embed-text also works); override with --model /
TCLAUDE_EMBED_MODEL and --url / TCLAUDE_OLLAMA_URL (default
http://localhost:11434).
Claude Code transcripts only
The semantic index reads Claude Code's transcript store. Codex, OpenCode, Copilot, Gemini, and pi conversations are not indexed.
Requirements: a running Ollama with the embedding model pulled:
Build or update the index, then query it:
tclaude conv index-embeddings # incremental, by file mtime
tclaude conv index-embeddings -r # full rebuild (needed after a model switch)
tclaude conv search-embeddings "that refactor where we split the parser"
tclaude conv search-embeddings -n 5 -l "flaky test investigation"
Indexing chunks each conversation (a metadata chunk plus ~24K-character
content chunks split at turn boundaries), embeds the chunks via Ollama, and
stores the vectors in tclaude's SQLite database. Embeddings are
model-specific, hence the -r rebuild when switching models. Queries rank
conversations by their best-matching chunk; -l shows the matched chunk
text, -j emits JSON, -g searches globally.
In watch mode, s enters semantic search — offering to index unindexed
conversations first — and adds a SCORE column; Esc returns to the normal
listing.
Conversation IDs and time filters¶
Conversation IDs are accepted as the full UUID, any unique prefix of 8+
characters, or the decorated form shell completion produces
(abc12345_[title]_prompt…).
Time filters take durations relative to now (24h, 7d, 2w) or dates
(2026-01-15, 2026-01-15T10:30):