ctx
Reference

Search

Search indexed agent sessions and retrieve cited context without model summarization.

ctx search finds matching indexed history. Default results are shaped around useful sessions: ctx shows the strongest matching span from each session, then lets you drill into dense event-level matches when one session looks relevant.

By default, search first performs a quiet best-effort refresh of discovered native provider sources and enabled custom history plugins, then queries the local SQLite store.

Examples

ctx search "build failure"
ctx search "sqlite storage" --provider codex
ctx search "retry handling" --workspace 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 --term "installer" --term checksum --term release
ctx search "token budget" --session <ctx-session-id>
ctx search "token budget" --events
ctx search "token budget" --limit 5 --verbose
ctx search "release notes" --history-source example-agent/default

Use repeatable --term when you want to search multiple explicit words or phrases, similar to rg -e foo -e bar. You can use --term on its own or together with a positional query.

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, session_importance, more_matches_in_session, and suggested_next_commands for typed commands such as ctx show event, ctx show session, and ctx locate event.

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|kilo|kiro-cli|crush|goose|lingma|qoder|warp|codebuddy|trae|openclaw|hermes|nanoclaw|astrbot|shelley|continue|openhands|antigravity|gemini|tabnine|cursor|windsurf|zed|copilot-cli|factory-ai-droid|qwen-code|kimi-code-cli|auggie|junie|firebender|forgecode|deepagents|mistral-vibe|mux|rovodev|cline|roo;
  • --history-source <plugin/source-or-provider_key/source_id> for imported custom history;
  • --provider-key <key>, --source-id <id>, and --source-format <format> for exact custom history source filters;
  • --workspace <name-or-path>;
  • --since <rfc3339-or-days>d;
  • --event-type <event-type>;
  • --file <path>;
  • --session <ctx-session-id>;
  • --term <query-or-keyword>, repeatable explicit search terms;
  • --events;
  • --include-subagents;
  • --limit <n>;
  • --refresh auto|off|strict;
  • --include-current-session;
  • --verbose.

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

The default searches primary-agent sessions so human intent and decisions stay prominent. Use --include-subagents when you want implementation details, code review notes, test output, or failure analysis from subagent sessions too.

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

Default search returns diverse session-level results. Use --session <ctx-session-id> after a default search has identified a session to inspect; scoped session search returns dense event hits. Use --events without --session when you want dense event-level results across sessions.

When ctx is run from Codex and CODEX_THREAD_ID is available, search excludes the active Codex session tree by default so the current prompt and its subagent work do not dominate history research. Use --include-current-session when you are intentionally looking for material from the active session tree.

--refresh defaults to auto. auto attempts a best-effort pre-search import of discovered native provider sources and enabled custom history plugins, then 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 --all when you need a full catch-up before querying. Use --refresh off to search the existing index without refreshing or running plugin commands. NanoClaw is explicit-import only, so import it through a supported project path before searching unless it is already indexed.

Machine output

Use default text output for agent reading. Use ctx search --json for scripts, jq, or exact field extraction. 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, and ctx locate session for deterministic cited retrieval. These commands return source material and do not call a model or generate a summary. Use ctx show session --format markdown --out <path> when you need a transcript artifact on disk.