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 and configured custom history plugin manifests. 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 provider-history 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 show, locate, and write to a transcript artifact;
• 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
  upgrade-state.json
  logs/

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

Official installer-managed binaries also write a sidecar next to the binary, such as ~/.local/bin/ctx.install.json, so ctx upgrade can verify that the install is allowed to self-upgrade.

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 search --term retry --term backoff --term timeout
ctx show event <ctx-event-id> --window 3
ctx show session <ctx-session-id>
ctx locate event <ctx-event-id>
ctx show session <ctx-session-id> --mode full --format markdown --out transcript.md

ctx search queries the local index and returns cited results. Default results are session-diverse so one large session does not crowd out the rest of the search page. Use repeatable --term for explicit multi-term searches and --session <ctx-session-id> when you want dense matches inside one session.

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 show session --format markdown --out <path> 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 native provider sources and enabled custom history plugins 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.

Run an explicit import when you need a full 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