/ctx-agent-history-search
Use ctx to search local coding-agent history before acting. Use when prior agent sessions may contain relevant insights, decisions, attempts, or transcript context.
$ npx -y skills add ctxrs/ctx --skill ctx-agent-history-search --agent claude-codeHow it fires
How this skill gets triggered: by you, by Claude, or both.
- Fires itselfAuto-invocation. Claude auto-loads it when your prompt matches the work.Auto-invocation is when the right skill fires by itself at the right moment, driven by a FLOW.md router and a hook, instead of you invoking it by name. It is the difference between a skill being installed and a skill actually getting used.Read the full definition →
- You can call itInvoke it directly when you want it.
- Slash command
/ctx-agent-history-search
Context preview
The summary Claude sees to decide when to auto-load this skill.
Use ctx to search local coding-agent history before acting. Use when prior agent sessions may contain relevant insights, decisions, attempts, or transcript context.
SKILL.md
ctx-agent-history-search.SKILL.mdname: ctx-agent-history-search
description: Use ctx to search local coding-agent history before acting. Use when prior agent sessions may contain relevant insights, decisions, attempts, or transcript context.
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
1. 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.
2. 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.
3. Inspect relevant results before relying on them:
ctx show event <ctx-event-id> --window 5
ctx show session <ctx-session-id>
4. 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>
5. 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.
1. 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. 2. 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. 3. Inspect focused sources before drawing conclusions.
Read more
name: ctx-agent-history-search description: Use ctx to search local coding-agent history before acting. Use when prior agent sessions may contain relevant insights, decisions, attempts, or transcript context.
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
1. 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.
2. 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.
3. Inspect relevant results before relying on them:
ctx show event <ctx-event-id> --window 5 ctx show session <ctx-session-id>
4. 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>
5. 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.
1. 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. 2. 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. 3. Inspect focused sources before drawing conclusions.
Repo: ctxrs/ctx