How ctx works

ctx turns existing local coding-agent history into a searchable SQLite index. A later agent can search for a phrase like failed migration, open the matching event, and inspect the session where that failure happened.

Discovery

ctx sources
ctx sources --json

Discovery checks known local history locations for supported agent harnesses. It reports what ctx can see on the current machine without launching those agents.

In JSON output:

• native_import says whether ctx has parser support for that provider format;
• importable says whether the source exists and has supported data available to import.

A provider can be supported by ctx and still have nothing importable on one machine. Common reasons include missing local history, an empty history file, a moved provider data directory, or an unsupported schema version.

Import

ctx setup
ctx import --all
ctx import --provider codex
ctx import --provider opencode --path ~/.local/share/opencode/opencode.db

ctx setup is the normal first-run path. It initializes local storage, discovers sources, imports discovered history, and optimizes the index.

ctx import is the explicit repair or catch-up path. Use it when you want to target a provider, pass a path, re-run an import, or produce structured output for automation.

Imports read provider-owned history. They do not write into source repositories, call model APIs, require API keys, or start a daemon.

Normalized sessions and events

Provider histories do not use one shared shape. Some store JSONL transcript trees, some use SQLite, and some store session state files.

ctx keeps provider metadata when it is useful, then writes a normalized model into its own store:

• sessions: the durable unit you can list, show, locate, and export;
• events: searchable turns, messages, tool calls, outputs, and other timeline items when the provider history exposes them;
• citations: pointers back to the provider source path or cursor when ctx can preserve one;
• searchable text: normalized text used by ctx search.

The IDs returned by ctx commands are ctx-owned IDs. Provider session IDs can appear as metadata, but commands such as ctx show event, ctx show session, and ctx locate use ctx IDs.

SQLite storage

By default, ctx stores its index under ~/.ctx:

~/.ctx/
  work.sqlite
  config.toml
  logs/

You can choose another root with CTX_DATA_ROOT or --data-root.

If text is searchable, assume a copy or normalized form exists in SQLite. Treat the ctx data root as local agent history: useful for retrieval, and sensitive in the same way the original transcripts are sensitive.

Search and retrieval

ctx search "retry handling"
ctx show event <ctx-event-id> --window 3
ctx show session <ctx-session-id> --mode lite
ctx locate event <ctx-event-id>
ctx export session <ctx-session-id> --mode full --format markdown

ctx search queries the local index and returns cited results. Event-level matches are preferred when the imported provider history has enough structure.

ctx show event opens one event with surrounding context. ctx show session opens the session. ctx locate event and ctx locate session report the original source location when it is known. ctx export session writes a session in a scriptable format for review or handoff.

These commands retrieve existing material. They do not summarize with a model.

Refresh behavior

ctx search "token budget" --refresh auto
ctx search "token budget" --refresh off
ctx search "token budget" --refresh strict

Search defaults to --refresh auto. The current auto-refresh path can run a bounded best-effort refresh of discovered Codex session sources before querying. If refresh cannot run, auto still searches the existing index.

--refresh off skips refresh and searches only the current index.

--refresh strict fails the search if the pre-search refresh cannot run or import successfully.

For non-Codex provider history, run an explicit import when you need a catch-up before searching:

ctx import --provider claude
ctx import --provider cursor
ctx import --all

JSON search output includes a top-level freshness object so scripts can tell which refresh mode ran and what happened.

Failure boundaries

ctx is conservative around unavailable or unclear source data. A source may be supported but not importable. A citation may point to a file that has moved since import. A search result may come from SQLite even when the original provider file is no longer present.

Use these commands to narrow the problem:

ctx sources --json
ctx import --provider <provider> --progress plain
ctx search "the missing phrase" --refresh strict
ctx doctor
ctx validate