# ctx: local search over your past coding agent sessions

> ctx indexes the JSONL and SQLite transcripts your coding agents already leave on disk, then lets you search them with BM25 or local embeddings. The free CLI is Apache-2.0; attribution back to a session is the paid ctx pro add-on.

**ctxrs/ctx** — Search the coding agent history already on your machine. | SDKs | Use ctx agent history search from TypeScript, Python, Rust, Go, JVM, Swift, or .NET code.

- Repository: https://github.com/ctxrs/ctx
- Website: https://ctx.rs
- Stars: 1,133 · Forks: 71
- Language: Rust
- License: Apache-2.0
- Published: 2026-08-04 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/ctxrs-ctx

## The transcript problem ctx is aimed at

Coding agents accumulate two kinds of history. Git records what the code became. The agent's own session transcripts and tool call records record why, and those stay in verbose log files that are awkward to read and worse to query. The README's framing is blunt: agents have git history, but their session logs are "sequestered away." So the knowledge exists on disk and is effectively unavailable at the moment a new session needs it.

ctx is for people running coding agents on their own machine who want that backlog searchable. The intended consumer is often another agent rather than a human: the README describes agents using search to surface earlier decisions and constraints, find investigations and failed approaches already tried, and resume prior work across threads. ctx also models how parent sessions, subagents and forks relate, so a chain of orchestrated work can be recovered rather than treated as unrelated files.

The README draws a line against "agent memory" tools that compact history into facts or summaries. ctx keeps the real record and searches it. That is a real difference in failure mode: a summary goes stale silently, while a missing index entry is at least visible as an empty result.

## How ctx discovers, normalizes and indexes sessions

The mechanism is a local pipeline over files that already exist. Session history typically lives in JSONL files or SQLite databases under directories such as ~/.claude and ~/.codex. The README states that ctx setup discovers those sources and reads them without modifying them, then converts each provider's format into consistent local records covering sessions, messages, tool calls, relationships and repository activity, and stores and indexes those records locally.

The workspace layout matches that description. The Cargo.toml lists separate crates per provider, including ctx-history-provider-claude-cursor, ctx-history-provider-codex, ctx-history-provider-gemini, ctx-history-provider-hermes, ctx-history-provider-mistral-mux, ctx-history-provider-openclaw-sqlite and ctx-history-provider-native-jsonl, alongside index crates such as ctx-history-index, ctx-history-index-format, ctx-history-index-generation and ctx-history-index-query. Provider support is therefore a per-crate concern, not a single parser with branches.

No hooks are required and nothing runs inside the agent process, according to the README. Automatic indexing is on by default and keeps the index current as the history sources change. Updates are completed before they become visible, so a command never reads a partially built index. Every session and event gets a stable ctx ID and keeps its full transcript content plus source information. Three commands split the work: ctx search finds history, ctx show retrieves an exact event or full transcript, and ctx locate identifies where it came from.

Default search is BM25 lexical matching. Semantic search computes embeddings locally and searches them directly, without a vector database to run. The README's efficiency claim is that structuring history into sessions, events, metadata and indexed fields and returning ranked cited matches costs far fewer tokens than raw transcript search, while noting that results vary by query and corpus.

## Install ctx and run a first search

The README gives install scripts for macOS, Linux and Windows PowerShell. On macOS or Linux the installer is piped to a shell:

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

On Windows PowerShell the equivalent is:

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

Either path should leave a ctx binary on your PATH. The README also offers a third route, prompting your agent to install and set up the CLI from github.com/ctxrs/ctx.

Indexing is the first real step. It walks the history sources it can find and builds the local index:

```bash
ctx setup
```

Expect this to take a while on a large backlog, since it reads whole transcripts. Once it finishes, a plain-language query returns matching sessions, snippets and ctx IDs:

```bash
ctx search "failed migration"
ctx search --file crates/foo/src/lib.rs
ctx search --term "failed migration" --term rollback --term "cursor rename"
```

The README shows results in the shape evt_01h..., ses_01h..., codex, followed by the matching text. The --file form is the one worth trying first if you already know which module is misbehaving. To read the surrounding transcript rather than the snippet, pass the event ID back to ctx show:

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

The --window 3 flag prints the matching part of the old transcript with surrounding context. If lexical search misses paraphrases, semantic search is opt-in:

```bash
ctx semantic enable
ctx semantic status
```

Enabling starts or recovers the daemon that acquires the local model and builds the semantic projection. The README notes a --wait flag to wait for readiness.

## Where ctx blame stops being able to help

ctx pro is the paid layer: attribution from a line, file, commit or PR back to the agent session that produced it. The README's own analogy is git blame for agent sessions, and the example starts from a line range:

```bash
ctx blame file src/checkout.ts --lines 118:146
ctx blame commit <sha>
ctx blame pr https://github.com/your-org/your-repo/pull/42
```

The output names a commit, a session ID and evidence citations, which you then open with ctx show session <id>. Pricing stated in the README is $20 USD per month, with a two-week trial requiring no account or credit card. Eligible fresh interactive installs start that trial automatically; existing users run ctx pro to set it up.

The limitation is stated plainly and it is the important one. Attribution only works for sessions present on your machine. If a teammate's agent produced the code, the README says ctx reports that it cannot prove the attribution. For a team where most commits come from other people's agents, ctx blame will frequently return that answer rather than a transcript. That is a correctness choice, not a bug, but it caps the tool's usefulness in shared repositories. The README also does not document rollback or uninstall for the pro setup, and the truncated material gives no detail on how the companion bridge in ctx-companion-bridge behaves.

## ctx against a general-purpose log or grep workflow

The obvious alternative is not another product but ripgrep plus jq over the raw JSONL files, or a full-text tool like a local grep index. That approach has one advantage: no indexing step and no format assumptions. It also has the costs ctx exists to remove. Raw transcripts are large, so a grep hit returns a wall of surrounding text that an agent must read, and the README argues raw search is often so token-heavy that it is effectively the same as having no usable history. Grep also has no notion of sessions, subagents or forks, so a match cannot be resolved back to a session ID, a parent session or a repository event.

ctx's answer is a normalized schema plus ranked, cited matches. The trade-off is that you inherit its provider coverage. If your agent writes a format no provider crate handles, the raw files are still grep-able and ctx is not. The workspace does include ctx-history-provider-native-jsonl, so a generic JSONL path exists, but the README does not document the schema that provider expects. Anyone with an unusual agent should check that before assuming coverage.

The second comparison is against hosted agent-memory services. Those move transcripts off the machine. ctx's README states that indexing, search and blame run locally, so code and history never leave the machine. For teams that cannot send source-adjacent transcripts to a third party, that constraint decides the choice on its own.

## Licence, maintenance and upgrade cost

The repository is licensed Apache-2.0, and the LICENSE file sits at the top level. That covers the CLI and the provider and index crates. It does not cover ctx pro, which the README describes as a paid add-on at $20 USD per month with a two-week free trial; the managed companion is documented separately in docs/managed-companion.md. The README does not state a separate licence for the pro components, so treat the paid boundary as a commercial term to read on its own rather than something the Apache-2.0 grant settles. This is a description of what the repository says, not legal advice.

The repository is not archived and the most recent push was on 2026-08-28, the same day as the v1.2.2 release. Releases v1.2.0, v1.2.1 and v1.2.2 all landed on 2026-08-28, which suggests a rapid patch sequence rather than a slow cadence. Upgrade tooling is present in the workspace as ctx-upgrade-engine, and the README documents no migration steps between index versions. Since the index is rebuilt locally from source transcripts, the practical upgrade cost is re-running ctx setup and, if you use it, rebuilding the semantic projection. The real cost to watch is disk and index time as your transcript backlog grows, not a paid upgrade path.

## Conclusion

Adopt ctx if your agents already write JSONL or SQLite transcripts under directories such as ~/.claude and ~/.codex and you want that history searchable without shipping it anywhere. Skip it if your agent keeps no on-disk session record, or if you need attribution from a session that ran on a teammate's machine, since ctx states it cannot prove that attribution. Before relying on it, run ctx setup, confirm ctx semantic status reports readiness if you want embedding search, and check that ctx blame covers the file and line range you care about.

## FAQ

### What does ctx stand for?

The README does not expand the name into anything. It uses ctx as the CLI name and as the prefix for generated identifiers such as evt_01h... and ses_01h..., so treat it as a name rather than an acronym.

### What does ctx mean in AI?

In this project it is a CLI for searching past coding agent sessions stored on your machine, not a model or a context-window setting. It indexes transcripts from agents such as Claude and Codex and returns ranked, cited matches.

### Does ctx send my session transcripts anywhere?

The README states that indexing, search and blame run locally, so your code and history never leave your machine. Semantic search computes embeddings locally and searches them directly, without a vector database to run.

### What is the difference between ctx and ctx pro?

The CLI indexes and searches local agent history and is licensed Apache-2.0. ctx pro is a paid add-on, listed at $20 USD per month with a two-week trial, that attributes a line, file, commit or PR back to the agent session that produced it.

### Why does ctx blame sometimes refuse to attribute code?

Attribution depends on the original transcript being on your machine. If a teammate's agent produced the code, the README says ctx reports that it cannot prove the attribution instead of guessing.

## Sources

- [Official documentation](https://ctx.rs)
- [Official README](https://github.com/ctxrs/ctx#readme)
- [Project repository](https://github.com/ctxrs/ctx)
- [Release notes](https://github.com/ctxrs/ctx/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ctxrs-ctx