ctx
Use with agents

Use ctx with Codex

Ask Codex to search local agent history with ctx, inspect cited results, and continue from prior work.

Install ctx first if it is not already available:

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

See Install for setup and data-root details.

Codex does not need a plugin to use ctx. It needs a clear instruction to search local history, inspect the cited result, and separate retrieved evidence from its own plan.

Prompt Codex to use ctx

Paste a prompt like this at the start of a task:

Before editing, use ctx to search prior local agent sessions for related work.

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

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

If the result affects your implementation, cite the `ctx_event_id` or `ctx_session_id` in your summary.

For a bug fix:

Use ctx to find prior sessions about the flaky migration failure. Inspect the best matching event with `ctx show event ... --window 3`, then explain whether the prior attempt changes your plan.

For a follow-up task:

Use ctx to find the previous session for the search ranking change. Inspect the session in lite mode, then continue from the cited decision if it still matches the code.

Commands Codex should run

Start broad enough to find the session:

ctx search "flaky migration failure" --json

Inspect the event when the result points to a specific moment:

ctx show event <ctx-event-id> --window 3

Inspect the session when the result points to the task as a whole:

ctx show session <ctx-session-id> --mode lite

Find the original source or export a transcript when a handoff needs provenance:

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

Choose the refresh mode

ctx search defaults to --refresh auto. That mode performs a quiet best-effort refresh for discovered Codex session sources, then searches the local index.

Use the existing index only:

ctx search "release checklist" --refresh off --json

Require freshness before searching:

ctx search "release checklist" --refresh strict --json

If the missing work came from another supported provider, ask Codex to import explicitly first:

ctx import --provider claude
ctx search "release checklist" --json

Cited output

Ask Codex to separate retrieved context from its own next step:

Retrieved context: `ctx show event <ctx-event-id> --window 3` shows that the
last attempt failed because the assertion expected the old cursor name.

Plan: I will check the current migration code and update the assertion only if
the cursor name changed in the same way.

The cited ctx ID lets a reviewer rerun the same command.