Ctx Agent History Search

ctx Agent History Search

Use ctx whenever you need to reference previous coding-agent sessions. Those

transcripts can contain user intent, decisions, previous work timelines, past

attempts, and what worked or failed.

Use this skill in two modes:

• retrieval before work, when prior sessions may contain decisions, commands,

failures, or citations that affect the current task;

• history research reports, when the user asks an agent or read-only subagent to

research a historical topic across prior local agent sessions.

Prerequisites

• Require the ctx CLI to be installed and set up. If it is missing and

installing tools is appropriate for the task, install it with:

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

• First setup can take time while ctx indexes past sessions. If needed, keep it

running in the background or in tmux, or wait for it to finish.

• If ctx remains unavailable, say local history search is unavailable and do not

invent results.

Workflow

• Confirm ctx is ready when starting from a cold context:

   ctx status
   ctx sources

Use ctx status --format json or ctx sources --format json only when a script needs

exact fields.

• Search with normal language first. Add terms or filters when useful:

   ctx search "<query>"
   ctx search "<query>" --refresh off
   ctx search "<query>" --provider codex
   ctx search "<query>" --workspace <workspace>
   ctx search "<query>" --file <path>
   ctx search "<query>" --since 30d
   ctx search "<query>" --term "<related term>" --term "<error text>"
   ctx search "<query>" --session <ctx-session-id>
   ctx search "<query>" --verbose

Use default text output for agent reading. Do not add --format json for

search or show unless you are piping it into jq or a script, or

you need exact machine-readable fields. JSON output is much larger and can

quickly consume the context window.

When the prompt asks for a topic history or report across multiple sessions,

run several ctx search queries with different wording and filters to find

promising sessions. Use scoped

ctx search "<query>" --session <ctx-session-id> when a session looks

relevant and you need dense event-level matches from that session.

Default search returns primary-agent sessions so human intent and decisions

stay prominent. Use --include-subagents when implementation details, code

review notes, test output, or failure traces from subagent sessions are

likely to matter.

Use --verbose when you need full ctx IDs, provider IDs, citations, and

copyable follow-up commands without switching to JSON.

You can write a session transcript to a temporary file, check the file size,

and then read the relevant parts:

   ctx show session <ctx-session-id> --format markdown --out /tmp/ctx-session.md
   wc -c /tmp/ctx-session.md

In Codex, ctx excludes the active session tree by default when

CODEX_THREAD_ID is available, so the current prompt and subagents do not

dominate historical retrieval. Use --include-current-session only when the

active session tree is the target.

• Inspect relevant results before relying on them:

   ctx show event <ctx-event-id> --window 5
   ctx show session <ctx-session-id>

• Locate original provider material when source identity or resume hints

matter. provider_session_id is the Codex resume UUID:

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

• Write a transcript of relevant sessions when you, the human, or another

agent needs a file:

   ctx show session <ctx-session-id> --format markdown --out <output-path>

When Search Needs Narrowing

Vary the query and use search filters before drawing conclusions. Useful

follow-ups include dense event search, session-scoped search, and source

location checks:

ctx search "<query variant>" --events --refresh off
ctx search "<query>" --session <ctx-session-id> --refresh off
ctx search "<query>" --include-subagents --refresh off
ctx show event <ctx-event-id> --window 5
ctx show session <ctx-session-id>
ctx locate event <ctx-event-id>
ctx locate session <ctx-session-id>

Search result windows are bounded. Do not claim exact corpus-wide counts or a

complete audit from the number of returned hits. If the requested conclusion

cannot be supported with search, show, and locate evidence, state that limit

and report the strongest retrieved evidence instead.

For advanced querying or complete deterministic event enumeration, use

ctx list events. Read the full filter, range, cursor, and output documentation

before use:

ctx docs show event-queries

History Research Reports

When asked to research a historical topic, stay read-only unless the user also

asks for edits. The agent writes the report; ctx only retrieves local source

material.

• Restate the topic, scope, and desired length if the prompt is ambiguous.

Prefer concise reports by default; use a longer report when the user asks for

chronology, alternatives, or detailed evidence.

• Run several targeted searches. Vary query terms across user wording, file or

module names, error text, commands, branch names, and decision terms. Start

with ctx search "<topic>", then broaden with --term or narrow with

--workspace, --provider, --file, --since, or

--session <ctx-session-id>.

Use --include-subagents when reviews, implementation attempts, test output,

or failure traces are likely to live in delegated sessions. Add

--refresh off when the report must not update the local ctx index.

• Inspect focused sources before drawing conclusions. Prefer ctx show event

for a hit plus nearby turns, and ctx show session when the whole session

arc matters:

   ctx show event <ctx-event-id> --window 5
   ctx show session <ctx-session-id>

Use full or log mode only when default output omits necessary evidence.

• Compare evidence across sessions. Note agreements, conflicts, stale results,

and gaps where searches did not find evidence.

• Produce the report as agent synthesis with citations.

Concise report shape:

• answer or finding;
• strongest supporting ctx IDs;
• important caveats or gaps;
• optional next search or verification step.

Long report shape:

• question and scope;
• search method, including key queries and filters;
• findings or chronology;
• evidence table with provider, ctx session ID, ctx event ID when available, and

why each source matters;

• conflicts, gaps, and suggested follow-up.

Citation Rules

• Cite ctx material when it affects your answer or implementation.
• Include the provider, ctx session ID, ctx event ID when available, provider

session ID when available.

• If you synthesize across multiple snippets, label the conclusion as your

synthesis and cite the supporting snippets.

• If a cited event or session is absent from the current Core generation, say

so and consider whether an explicit ctx import is appropriate.

Safety Rules

• Prefer text output for agent reading. Use JSON only for scripts, jq, or

exact field extraction, and keep JSON outputs small.

• Do not say ctx inferred a decision unless the cited text explicitly states

that decision.

• Do not state that ctx wrote model analysis.
• Do not paste raw transcripts, large JSON payloads, secrets, tokens, or private

paths into a user-facing report. Summarize reviewed evidence and quote only

short excerpts needed to support a claim.

• Treat ~/.ctx, provider transcript paths, and JSON output as private local

history unless the user explicitly asks to share reviewed excerpts.