ctx

# 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:

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

  Windows PowerShell:

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

- If ctx is installed but not initialized, run:

  ```bash
  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:

```bash
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:

```bash
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:

   ```bash
   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:

   ```bash
   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:

   ```bash
   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:

   ```bash
   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:

   ```bash
   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 asks
  to start or enable the trial.
- If status reports expired or locked access, explain that blame is unavailable
  until Pro access is restored and that existing local Pro data is preserved.
  When blame would materially help, recommend `ctx pro manage` to restore
  access. Do not guess why access is locked, purchase a subscription, modify
  billing, or open a billing flow without explicit human approval. Continue
  with history search when it can still help.
- If stat