Search

ctx search finds matching indexed history, with event hits preferred when event context is available. By default it first performs a quiet best-effort refresh of discovered Codex session sources, then queries the local SQLite store.

Examples

ctx search "build failure"
ctx search "sqlite storage" --provider codex
ctx search "retry handling" --repo checkout --since 60d
ctx search "tool output" --event-type tool_output
ctx search --file crates/foo/src/lib.rs
ctx search "token budget" --refresh off
ctx search "token budget" --limit 5 --json

Results can include ctx_event_id, ctx_session_id, provider metadata, title or event label, snippet, rank, match reasons, timestamp, working directory, source path or cursor when available, citations, and suggested_next_commands for typed commands such as ctx show event, ctx show session, ctx locate event, and ctx export session.

Search result IDs are ctx-owned. Provider-owned session IDs are exposed as metadata so humans can recognize the original provider session, but positional lookup commands use ctx_event_id and ctx_session_id.

Filters

• --provider codex|pi|claude|opencode|antigravity|gemini|cursor|copilot-cli|factory-ai-droid;
• --repo <name-or-path>;
• --since <rfc3339-or-days>d;
• --event-type <event-type>;
• --file <path>;
• --primary-only;
• --include-subagents;
• --limit <n>;
• --refresh auto|off|strict.

--since accepts RFC 3339 timestamps such as 2026-06-01T00:00:00Z or a day window such as 30d.

The default includes subagent material. --primary-only excludes it unless --include-subagents is also passed.

--limit defaults to 20 and is capped at 200.

--refresh defaults to auto. auto attempts a best-effort pre-search import of discovered Codex session sources and serves the existing index if that refresh fails. On large discovered sources or already-cataloged indexes, auto serves current results without a foreground catch-up scan. Use --refresh strict or ctx import --provider codex when you need a full catch-up before querying. Use --refresh off to search the existing index without refreshing. The current pre-search refresh path is limited to discovered Codex session sources; other providers are searched from the existing index until they are explicitly imported.

Machine output

Use ctx search --json for agent workflows and scripts. JSON results include the same result metadata and citations as the human output, plus a top-level freshness object describing the pre-search refresh mode and outcome. A citation with source_exists: false means ctx can return indexed text, but the raw provider file was not available at the stored path when the result was built.

Cited retrieval

Use ctx search, ctx show event, ctx show session, ctx locate event, ctx locate session, and ctx export session for deterministic cited retrieval. These commands return source material and do not call a model or generate a summary.