ctx: A Local Search Engine for Your Coding Agent's Session History

The Problem: Agent Transcripts Are Trapped in Log Files

Coding agents like Claude Code and Codex generate verbose logs of every message, tool call, and decision. Those logs sit in directories like ~/.claude and ~/.codex, usually as JSONL or SQLite files. They are a record of what the agent did and why, but they are not legible to the next agent session. A new session cannot quickly ask 'what did we try for the migration failure last week?' without dumping entire files into context. That is expensive in tokens and often impractical. ctx solves this by turning those raw logs into a structured, searchable index that lives on your machine. The README's core claim is that this gives agents 'instant recall of the real record' without a lossy memory step. The target user is anyone who runs multiple agent sessions and wants to avoid repeated work, lower token spend, and recover context that disappears once a session ends.

How ctx Structures and Indexes Your History

The mechanism is straightforward. ctx setup scans known directories for agent history files. It reads them without modifying them, then converts each provider's format into consistent local records. Those records cover sessions, messages, tool calls, relationships between parent sessions and subagents, and repository activity. Each record gets a stable ctx ID, such as ses_01h... or evt_01h..., and retains the full transcript content and source information. The index is built locally, and automatic indexing keeps it current as the history files change. The README states that each update completes before it becomes visible, so commands never read a partially built index. That is a concrete design choice that avoids the classic problem of seeing half-written entries during a search. The search itself uses BM25 lexical matching by default. You give it likely terms like an error message, a file path, or a command, and it ranks sessions containing those terms. For cases where different wording is used for the same idea, ctx offers semantic search, which computes embeddings locally and searches them directly. No vector database is required. You enable it with ctx semantic enable and check status with ctx semantic status. The daemon acquires the local model and builds the semantic projection.

Getting Started: Install, Setup, and First Search

Installation is a one-liner for macOS and Linux: curl -fsSL https://ctx.rs/install | sh. Windows uses PowerShell with irm https://ctx.rs/install.ps1 | iex. After installation, you run ctx setup to index all local agent sessions. The README gives a concrete example: your agent searches for 'failed migration' with ctx search "failed migration". You can narrow by file with --file crates/foo/src/lib.rs, or combine multiple terms with --term flags. Results include session IDs and snippets, so the agent can immediately see which session is relevant. To print the matching part of an old transcript, use ctx show event <ctx-event-id> --window 3, which shows three events around the match. That is a practical workflow: search, then show, then act on the recovered context. The setup command discovers sources like ~/.claude and ~/.codex, but the README does not list every supported provider. You should verify that your specific agent's log location is covered.

ctx blame: Attribution with a Catch

The standout feature is ctx blame, part of the paid ctx pro tier. It is described as 'git blame, but for agent sessions.' Given a file, line range, commit, or PR, ctx blame finds the agent session that produced that code. The example shows ctx blame file src/checkout.ts --lines 118:146 returning a commit hash and a session ID, with evidence citations like [1] and [2]. The agent can then open the transcript with ctx show session <id> and see the original reasoning, including tool calls. This is powerful for auditing and for recovering decisions that are no longer visible in the code. However, there is a hard limitation: attribution only works if the session is on your machine. If a teammate's agent produced the code, ctx says it cannot prove the attribution. That is an honest boundary. The feature also supports commits and PRs directly: ctx blame commit <sha> and ctx blame pr <url>. The pricing is $20 per month, with a two-week free trial that requires no account or credit card. The README says eligible fresh interactive installs start the trial automatically, but it does not define 'eligible.' You will need to check the docs for that detail.

Token Efficiency: The 50x Claim and Its Limits

The README claims ctx is '50x more token-efficient than raw transcript search.' That number is presented as a general result, but the text immediately qualifies it: 'Results vary by query and corpus.' That is an honest caveat, but it means you should not take 50x as a guarantee. The efficiency comes from structuring history into sessions, events, metadata, and indexed fields, then returning ranked cited matches. Instead of dumping raw log text into the context window, the agent gets a short snippet and a citation. That can dramatically reduce tokens for a typical query. But for a query that matches everything, or a corpus that is tiny, the savings will be smaller. The README also notes that raw search is often so token-heavy that it is 'effectively the same as not having usable history.' That is the core motivation. The mechanism is sound: BM25 ranking picks the most relevant sessions, and the agent only fetches the full transcript for the top hits. This is a practical approach that balances recall and cost.

Limitations and When ctx Is the Wrong Tool

ctx has several real limitations. First, it only works with history that is local. If you run agents on a remote CI server or a teammate's machine, ctx cannot index that history. The blame feature explicitly fails in that case. Second, the README does not enumerate all supported agent providers. It mentions ~/.claude and ~/.codex, but not others like Gemini CLI or Cursor. If your agent writes logs to a non-standard location, ctx setup may not find it. You will need to check the documentation or test it. Third, semantic search requires a local model download, which has a disk and compute cost. The daemon that acquires the model must be running, and there is a --wait flag to wait for readiness. That adds operational complexity. Fourth, the tool is a CLI and SDK, not a GUI. If you want a visual browser of your agent history, this is not it. Finally, the free tier's exact limits are not stated in the README. The pro tier is clearly defined, but the open-source core's search capabilities are not bounded in the material. That uncertainty could matter for heavy users.

Alternatives: Agent Memory Systems and Raw Log Search

The most direct alternative is what the README calls 'agent memory' systems, which compact past sessions into facts or summaries. Those tools give you a distilled version of history, but they are lossy. ctx explicitly positions itself against that approach: it gives the full transcript, not a summary. The trade-off is storage and retrieval speed. A summary is small and fast to load, but it can be stale or miss nuance. ctx is heavier but exact. Another alternative is raw grep or ripgrep over the log files. That works, but it returns entire lines or blocks of JSONL, which are token-heavy and unstructured. You get no ranking, no session grouping, and no relationship awareness. ctx adds structure: it understands parent sessions, subagents, and forks, so you can recover the whole chain of work. That is something a simple text search cannot do. If you need attribution to a specific session, raw log search cannot give you that without manual cross-referencing. ctx blame automates it, but only with the paid tier.

Maintenance, Upgrade Cost, and License Implications

The project is written in Rust and licensed under Apache-2.0, which is permissive for the open-source core. The last push was August 28, 2026, with three releases in one day, suggesting active maintenance. The upgrade path is simple: re-run the install script or use your package manager if you installed that way. The daemon for semantic search needs to be managed; it runs automatically after you enable semantic, but you should monitor its resource usage. There is no documented migration path for the index between versions, but the stable release cadence suggests backward compatibility. The main license caveat is ctx pro: it is a paid add-on, not open source. The README does not state its license, so any integration that relies on blame functionality must account for that. The core search and show commands are free, but the attribution feature is gated. If you build tooling around ctx blame, you are dependent on a commercial product. That is a risk to evaluate. The SDKs listed (TypeScript, Python, Rust, Go, JVM, Swift, .NET) suggest a broad integration surface, but the README does not provide code examples for them, so you will need to consult the docs to learn the API.

Editorial conclusion

Adopt ctx if you work with coding agents like Claude or Codex and need to retrieve past decisions, failed approaches, or tool call details without feeding entire log files to your model. Do not adopt it if you require cloud-based centralization or if your history lives on a remote machine that ctx cannot index. Before relying on it, verify that ctx setup discovers all the providers you use, and test the token savings on your own queries, since the claimed 50x efficiency depends on corpus and query. Also check whether the free tier covers your needs or whether the $20 monthly ctx pro is justified by your attribution use cases. The project is Apache-2.0 and actively maintained, but the blame feature is proprietary, so review the licensing implications before building internal tooling around it.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes