qmd-cli

disable-model-invocation	true
name	qmd-cli
description	Search indexed text corpora with qmd. For indexed content, prefer qmd over grep.

text-search

Use qmd to search indexed text corpora such as session logs, notes, docs, and logs. For indexed content, use qmd for discovery instead of raw grep.

First checks

Before searching, confirm what is indexed:

qmd status
qmd collection list
qmd context list

Do not assume collection names, paths, or contexts.

Core rule

For indexed corpora, use qmd for discovery.

Do not use grep/find/jq/cat directly on indexed files to search for meaning. This is especially important for session JSONL, which is noisy and hard to interpret raw.

Shell usage is still fine for:

• filtering tool output after discovery
• housekeeping and file targeting
• non-indexed content
• helper scripts in this skill

Choose the right qmd command

For exact clues, start with qmd search.

• Use qmd search for exact clues: tool names, error strings, repo names, JSON fields, literal phrases
• Use qmd query when lexical search is weak, the request is conceptual, or you want hybrid retrieval + reranking
• Use qmd vsearch only when you specifically want pure semantic similarity

qmd search '"toolName":"rp_exec"'
qmd search 'apply_edits'
qmd query "OAuth redirect flow"
qmd vsearch "the session where we changed direction"

Operational notes:

• qmd query may trigger local model startup or model downloads, so it is not always the fastest first step
• For session discovery, prefer --files first so you get compact path output instead of long snippets

Build better queries

Use --intent when the request is ambiguous

intent is a steering hint. Use it when the same words could refer to multiple things or when the user remembers the topic better than the exact wording.

qmd query --intent "Pi/Codex/Claude agent sessions about repo editing failures" \
  -c sessions \
  "apply_edits error"

Use structured query documents for important searches

Multi-line query documents are useful when you have both exact clues and fuzzy memory.

• lex: exact terms, phrases, identifiers, JSON fields
• vec: natural-language meaning
• hyde: what the answer likely looked like
• intent: optional steering context

qmd query $'intent: agent sessions about RepoPrompt edits and patch failures
lex: apply_edits rp_exec "search block not found"
vec: debugging failed file edits in agent sessions
hyde: The agent tried to edit a file several times, the edit did not match, and it switched to a narrower or different approach'

Operational details:

• The first typed query gets 2x fusion weight, so put the strongest signal first
• expand: must stand alone; do not mix it with typed lines
• lex queries support quoted phrases and exclusions such as -sports or -"test data"

Useful output and tuning flags

qmd query --files -n 20 "agent session about flaky tests"
qmd query --json -n 10 "session where we redesigned the search flow"
qmd query --json --explain -c sessions "apply_edits error"
qmd query -C 20 --min-score 0.3 -c sessions "OAuth redirect flow"

Use:

• --files for compact discovery output and path-based follow-up
• --json for structured inspection when you need scores/snippets
• --explain when ranking looks wrong
• -C, --candidate-limit to reduce reranking work
• --min-score to drop weak matches
• -c, --collection to scope the search

For session hunting, --files is usually the best first output mode.

Retrieval commands

qmd get "#abc123"
qmd multi-get "docs/*.md" --json
qmd ls sessions
qmd ls sessions/claude

Use get, multi-get, and ls to retrieve or browse content after discovery.

For session discovery, use this inspection path:

# 1. Discover a session transcript
qmd search -c sessions --files 'apply_edits' -n 5

# 2. Read the session transcript directly
qmd get "qmd://sessions/path/to/session-transcript.md" --full

Each session transcript includes original_session metadata in frontmatter. When exact tool outputs, commands, SQL, or ad-hoc code matter, recover them from the original session JSONL with session_ask or session-view --include-tool-results.

If qmd is missing

npm install -g @tobilu/qmd
qmd --version
qmd status

---

Sessions

Agent session transcripts are indexed as the sessions collection.

The sessions collection is a corpus of agent session transcripts generated from session JSONL via session-view. It is optimized for readable search. Very large sessions may be split across multiple transcript documents; use the original_session metadata when you need exact raw-session recovery.

Required workflow

Use this three-step process:

1. Discover candidate sessions with qmd or analyze-sessions.sh
2. Inspect the session transcript with qmd get
3. Recover exact raw-session details only when needed via original_session + session_ask or session-view --include-tool-results

Do not try to understand a session from raw JSONL snippets alone.

Inspecting session transcript paths

Use one reliable inspection path:

# Read the session transcript directly
qmd get "qmd://sessions/path/to/session-transcript.md" --full

If the transcript is enough, stop there.

If exact raw-session details matter:

# 1. Read the transcript and note its `original_session` frontmatter
qmd get "qmd://sessions/path/to/session-transcript.md" --full

# 2. Recover exact details from the original session
session-view --include-tool-results /absolute/path/to/original/session.jsonl

Or use session_ask against that original_session path when you want targeted recovery without reading the whole session.

Filtering transcript output is fine:

qmd get "qmd://sessions/path/to/session-transcript.md" --full | grep -iE 'USER:.*(error|bug|regression)'

Session search playbook

Ask for narrowing clues when memory is vague

If the request is fuzzy, ask for:

• approximate timeframe
• which agent/tool produced the session
• repo or project involved
• remembered phrase, error text, or tool name

After 2-3 bad searches, stop iterating blindly and ask for more context.

Exact session search

Start here when you have hard clues. Use --files first to avoid wasting tokens on snippets. If lexical search returns an obvious hit, inspect it immediately instead of escalating to query.

qmd search -c sessions --files 'rp_exec' -n 20
qmd search -c sessions --files 'apply_edits' -n 20
qmd search -c sessions --files 'git rebase' -n 20
qmd search -c sessions --files 'search block not found' -n 20

If lexical search returns many same-score candidates because the clue is broad or common, do not keep repeating broad lexical searches. Tighten the query with a more distinctive phrase, tool name, error string, or timeframe clue, or switch to qmd query --intent ....

Escalate when lexical search is weak

Use query, add intent, and scope to sessions when exact search is weak or the request is conceptual. Keep --files on unless you specifically need snippets.

qmd query --intent "Pi/Codex/Claude agent sessions about git trouble during implementation work" \
  -c sessions \
  --files \
  -n 10 \
  "git rebase gone wrong"

Mixed exact + fuzzy session search

qmd query -c sessions --files $'intent: agent sessions about broken code edits in RepoPrompt workflows
lex: apply_edits rp_exec "oldText" "search block not found"
vec: session where file edits failed repeatedly and the agent had to retry'

Browse after narrowing

qmd ls sessions
qmd ls sessions/claude
qmd ls sessions/pi

Inspect with session-view

session-view lives at ~/.pi/agent/skills/text-search/scripts/session-view.

Use it when a session transcript points you at an original_session and you need exact raw-session details. It also accepts RepoPrompt AgentSession-*.json files when you want the compressed RP-side view plus its codexRolloutPath. For Codex sessions, session-view strips the leading injected AGENTS/environment preamble through </environment_context> before rendering the transcript.

# Default: omit tool result/output blocks
session-view /absolute/path/to/original/session.jsonl

# Opt-in: include tool result/output blocks
session-view --include-tool-results /absolute/path/to/original/session.jsonl

# RepoPrompt AgentSession JSON
session-view ~/Library/Application\ Support/RepoPrompt/Workspaces/.../AgentSessions/AgentSession-ABC123.json

You can also inspect the latest local session directly:

# Default: omit tool result/output blocks
session-view --latest pi
session-view --latest codex
session-view --latest claude
session-view --latest rp

# Opt-in: include tool result/output blocks
session-view --include-tool-results --latest pi

Rendered output looks like this (tool calls are shown; tool results are omitted by default):

USER: message

ASSISTANT: response text
  [tool_name] key_args

If you opt-in to tool results with --include-tool-results, you'll also see:

TOOL [name]: ✓ truncated_output

Example workflows

Find a specific session with hard clues

# 1. Start with lexical search and compact path output
qmd search -c sessions --files 'git rebase' -n 20

# 2. Inspect the transcript
qmd get "qmd://sessions/path/to/session-transcript.md" --full

# 3. If exact details matter, recover them from original_session
session-view --include-tool-results /absolute/path/to/original/session.jsonl

Escalate when lexical search is weak

qmd query --intent "Pi/Codex/Claude sessions about git trouble during coding work" \
  -c sessions \
  --files \
  -n 20 \
  "git rebase gone wrong"

Supplemental helper: analyze-sessions.sh

Location: ~/.pi/agent/skills/text-search/scripts/analyze-sessions.sh

Use it for time-windowed or operational reporting rather than ranked corpus search.

~/.pi/agent/skills/text-search/scripts/analyze-sessions.sh --hours 24 --report
~/.pi/agent/skills/text-search/scripts/analyze-sessions.sh --hours 48 --pattern "apply_edits|rp_exec"
~/.pi/agent/skills/text-search/scripts/analyze-sessions.sh --hours 36 --edit-diagnostics
~/.pi/agent/skills/text-search/scripts/analyze-sessions.sh --hours 48 --tool-errors
~/.pi/agent/skills/text-search/scripts/analyze-sessions.sh --hours 24 --tool-stats
~/.pi/agent/skills/text-search/scripts/analyze-sessions.sh --hours 72 --report --project pi-mono
~/.pi/agent/skills/text-search/scripts/analyze-sessions.sh --hours 72 --tool-stats --tool rp_exec

Use qmd for ranked discovery across the corpus. Use analyze-sessions.sh for recent-window reports and regex-style operational triage.

Session JSONL structure reference

Each JSONL line has a type field:

Type	Key fields
message	role, content, toolCall
toolResult	toolName, isError, content
custom	customType, data