/ctx

name: ctx
description: Use ctx as working memory for prior agent work. Before starting or continuing work in an unfamiliar area, resuming earlier work, or revisiting an investigation, search prior sessions to ground yourself in earlier context. When ctx blame is available, use it to trace a line, file, commit, or PR to the agent session that produced it. Use when prior decisions, constraints, attempts, tool calls, transcript evidence, or code provenance may matter.

ctx

Use ctx to ground your work in relevant prior agent sessions. Search local history for earlier decisions, constraints, attempts, and evidence. When ctx blame is available, use it to trace code and Git artifacts to the agent session that produced them.

ctx retrieves source material; you perform the analysis. Keep every conclusion grounded in the retrieved evidence.

Prerequisites

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

installing tools is appropriate for the task, use the installer for the current platform.

macOS and Linux:

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

Windows PowerShell:

  irm https://ctx.rs/install.ps1 | iex

• If ctx is installed but not initialized, run:

  ctx setup

• First setup can take time while ctx indexes past sessions. Allow setup to

finish or keep it running in an appropriate background session.

• If ctx remains unavailable, say so and do not invent history or provenance.

Get help and full documentation

This skill provides top-level workflow guidance, not a complete ctx command reference. When exact command behavior, options, output formats, installation, or troubleshooting details matter, consult help from the installed version rather than guessing:

ctx <command> --help
ctx docs search "<topic>"
ctx docs show <topic>
ctx docs list

Prefer `ctx docs search` and `ctx docs show` for agent use because they return concise text and match the installed ctx version. When a man-page view is useful, run:

ctx docs man --print ctx

Use [ctx.rs](https://ctx.rs) for the product website and documentation. Use [GitHub](https://github.com/ctxrs/ctx) for source, releases, and issues. Treat these as secondary resources; prefer installed help for command details.

Choose history search or Pro blame

• Search local history when the request concerns a topic, decision, constraint,

error, command, file, prior attempt, or previous session.

• Use ctx blame when the request starts from a line, file, commit, or PR and

asks which agent session produced it or why it was written that way.

• Combine both when blame identifies a session and broader search is needed to

find related investigations or follow-up work.

Search local history

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. Otherwise, it is less token-efficient than default output formatting.

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

   ctx search "<query>"
   ctx search "<query>" --workspace <workspace>
   ctx search "<query>" --file <path>
   ctx search "<query>" --since 30d
   ctx search "<query>" --session <ctx-session-id>

These are entry points, not a complete option reference. Use `ctx search --help` or `ctx docs show search` for all search filters and behavior.

Prefer default text output for agent reading. Use `--format json` only when piping to `jq` or a script, or when exact machine-readable fields are required.

Run several searches with different wording for topic research. Use a session-scoped search when one result looks relevant and dense event-level matches are needed.

Ordinary search already covers primary and subagent work, returning one best result per root task before repeats. Use `--primary-only` only when the task deliberately calls for a narrow primary agent search.

Use `--verbose` for full ctx IDs, provider IDs, source details, and copyable follow-up commands without switching to JSON.

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:

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

5. Write a transcript when the user or another agent needs a file:

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

Direct CLI searches automatically exclude the current session tree for Codex, DeepSeek Harness, Grok Build, Pi, Claude Code, Goose, Hermes, Shelley, Qwen Code, and Mux when the current session can be identified unambiguously. Unsupported or ambiguous detection fails open: ctx leaves the history included. `--include-current-session` restores the automatically excluded tree. Repeat `--exclude-session <ctx-uuid-or-unambiguous-prefix>` to exclude exact named sessions; the option is repeatable and conflicts with `--session`. MCP searches do not automatically exclude the caller's session.

Trace code with ctx blame

ctx blame requires Pro access. Determine availability from `ctx status` or a typed ctx failure; do not infer commercial state.

• If the trial is active, a paid subscription is active or canceling but still

paid through, or valid offline grace applies, use blame whenever it is relevant without asking again about Pro access.

• If Pro has not been activated and an eligible free trial may be available,

explain that blame needs Pro and offer to start the trial with `ctx pro`. Starting the trial consumes its one-time time window, so run `ctx pro` only after the human approves, unless the current request already explicitly