Use ctx with Claude Code

Install ctx first if it is not already available:

curl -fsSL https://ctx.rs/install | sh

See Install for setup and data-root details.

Claude Code can use ctx because it can run shell commands and inspect command output. The installable guidance below teaches it to check local session history, open the cited event or session, and include the ctx ID when retrieved history affects the answer.

Install the guidance

This makes the workflow easier to reuse across projects. Add the ctx plugin marketplace, then install the guidance:

/plugin marketplace add ctxrs/ctx
/plugin install ctx-agent-history-search@ctx

After installation, Claude Code can load ctx-agent-history-search when prior local agent sessions may contain relevant commands, attempts, decisions, or transcript context.

To verify it, open /plugins in Claude Code and confirm ctx-agent-history-search is installed. In a new task, ask Claude Code to use ctx agent history search; it should begin by checking ctx status --json before searching.

If you have not installed the skill yet, paste this guidance into Claude Code when you want it to use ctx:

Use ctx before changing code if prior agent work could answer part of this task.

Run a focused search:
ctx search "<query>" --json

Inspect the best match before relying on it:
ctx show event <ctx-event-id> --window 3
ctx show session <ctx-session-id> --mode lite

If you need the source file path or full transcript, run:
ctx locate event <ctx-event-id>
ctx export session <ctx-session-id>

When you use retrieved context, cite the `ctx_event_id` or `ctx_session_id` and say which command produced it.

Search first

Ask Claude Code for a narrow search tied to the decision you need:

Before editing, use ctx to search prior local agent sessions for the last time we touched the auth redirect flow. Inspect the best event with a small window, then summarize the relevant finding with the ctx_event_id you used.

Claude Code should start with:

ctx search "auth redirect flow" --json

If results look stale and the work was likely done in Codex, require a fresh pre-search import:

ctx search "auth redirect flow" --refresh strict --json

If you want only the current index:

ctx search "auth redirect flow" --refresh off --json

Inspect the hit

Search results should lead to one of these commands:

ctx show event <ctx-event-id> --window 3
ctx show session <ctx-session-id> --mode lite

Use ctx show event when a specific command, error, diff note, or decision appears in the search result. Use ctx show session --mode lite when the result points to a longer thread and Claude needs the surrounding task shape.

Ask for the cited finding before Claude edits:

I found the prior redirect change in ctx_event_id evt_... via
`ctx show event <ctx-event-id> --window 3`. The callback handler changed after
the provider started returning relative paths. I will check that handler before
editing.

Locate or export for provenance

When Claude Code needs the raw provider file or a full transcript, ask it to continue from the ctx ID:

ctx locate event <ctx-event-id>
ctx export session <ctx-session-id>

Use locate when you need to open the original provider history file. Use export session when the full transcript should be attached to an issue, review, or handoff after you have checked it for sensitive local content.

Keep the handoff cited

Ask Claude Code to include ctx citations in its final summary:

In your final response, include the ctx_event_id or ctx_session_id for any prior-session evidence you used. Do not describe it as memory. Treat it as retrieved local history.

A later agent can rerun the same ctx show event, ctx show session, ctx locate event, or ctx export session command instead of guessing which transcript supported the claim.