ctx

You already have months of coding agent history on your machine. ctx lets you search it and blame code to the sessions that wrote it. ctx graph maps relationships across your codebase, and ctx sift cuts noisy tool output before your agent reads it.

Together it is an open, local, fast CLI toolchain for context engineering.

Install and set up ctx

macOS and Linux:

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

Windows PowerShell:

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

or prompt your agent:

Please install and set up ctx CLI (see github.com/ctxrs/ctx)

Building from source? See the source-build instructions.

Search your agent history

Coding agents have git history, but their own session transcripts and tool call records remain sequestered away in verbose log files. Those log files are a treasure trove of useful data, but they aren't accessible in a legible format for agents.

If you give your agents fast, easy access to search and retrieve these transcripts, your agents can:

• surface decisions, constraints, and assumptions from earlier work
• find investigations, solutions, and failed approaches already explored in previous sessions
• audit previous sessions in detail
• pick up where previous work left off, even across multiple threads

That means less repeated agent work, lower token spend, and better task outcomes because each new session can use the history already on your machine.

ctx also understands how parent sessions, subagents, and forks relate to one another, so agents can recover the whole chain of work no matter how aggressively you orchestrate.

This is different from “agent memory,” which usually compacts what happened into facts or summaries that can become stale. ctx gives agents instant recall of the real record without a lossy memory step.

Your past coding agent sessions already live on your machine, usually in JSONL files or SQLite databases under directories such as ~/.claude and ~/.codex.

ctx setup discovers those sources and reads them without modifying them. It converts each provider’s format into consistent local records for sessions, messages, tool calls, relationships, and repository activity, then stores and indexes those records locally.

ctx does not require hooks or any code running inside the agent process. Automatic indexing is on by default and keeps the index current as those history sources change. Each update is completed before it becomes visible, so commands never read a partially built index.

Every session and event receives a stable ctx ID and retains its complete transcript content and source information. ctx search finds the relevant history, ctx show retrieves the exact event or full transcript, and ctx locate identifies where it came from. Semantic search and Blame use those same records.

# Index all of your existing local agent sessions
ctx setup

# Your agent can search prior work with normal language
ctx search "failed migration"

# Search sessions and events that touched a file
ctx search --file crates/foo/src/lib.rs

# Or search multiple terms
ctx search --term "failed migration" --term rollback --term "cursor rename"

# Results include matching sessions, snippets, and ctx IDs
# evt_01h...  ses_01h...  codex  "migration expected the old cursor name" ...

# Print the matching part of the old transcript
ctx show event <ctx-event-id> --window 3

# Or print a compact transcript of the original session
ctx show session <ctx-session-id>

Search uses BM25 lexical matching by default. Give it likely terms—an error, file, command, or decision—and it ranks sessions containing those terms.

Semantic search

Semantic search helps when related ideas use different wording. ctx computes embeddings locally and searches them directly, without a vector database to run. Enable it with:

ctx semantic enable
ctx semantic status

Lexical search stays available while the local model builds. The built-in model needs no API key; an explicitly configured external semantic executor can send history and query text to its endpoint. See retrieval backends for setup and privacy details. Transcript text is preserved rather than automatically redacted, so review copied output before sharing it outside your machine.

For the full pipeline, see How ctx works. For a quick first run, see Quickstart.

50x more token-efficient than raw transcript search

By structuring agent history into sessions, events, metadata, and indexed fields, then returning ranked cited matches, agents can access meaningful history with far fewer tokens than raw search. Results vary by query and corpus, but raw search is often so token-heavy that it can be effectively the same as not having usable history.

Back up and share history (beta)

Back up your agent history, or share selected sessions with your team through a ctx server you control. Your history stays local by default. Sharing is opt-in.

Setup guide.

Blame code to the agent that wrote it

git blame tells you which commit last changed a line. ctx blame tells you which agent session produced that commit, with exact citations back to the original transcript and recorded tool calls.

Agents use ctx blame to recover context that no longer exists anywhere near the current session. Starting from a file, line range, commit, or PR, they can find the relevant historical agent sessions and recover the decisions, constraints, failed approaches, and assumptions recorded there.

This helps agents:

• recover constraints and decisions no longer visible in the code
• uncover assumptions embedded in earlier changes
• avoid retrying approaches that already failed
• resume work without relying on lossy compaction summaries
• audit past agent work to improve instructions, tools, and workflows

Every attribution includes citations back to the original transcript and tool calls. If the session is not on your machine (for example, because a teammate’s agent produced the code), ctx says it cannot prove the attribution.

# Your agent is investigating why customized cart items
# are disappearing from your e-commerce app.
$ ctx blame file src/checkout.ts --lines 118:146

# ctx blame finds the agent session that produced those lines:
# Lines 118–146
#   commit    8f3c2a1
#   Produced by
#     session   c0297b8a-2ad7-4f73-a826-8ee9387cd1f4
#     evidence  [1] [2]

# Your agent opens the transcript of the session that produced the offending commit
$ ctx show session c0297b8a-2ad7-4f73-a826-8ee9387cd1f4

# Previous agent — transcript excerpt
"Some responses contain multiple cart lines with the same product_id.
I'm treating those as duplicates and merging them before calculating the total."

# Your agent finds the mistake
"FOUND IT: The previous agent treated matching product_ids as duplicate cart lines.
Customized items can share a product ID, so that merge drops valid items."

ctx blame can also start from a commit or PR:

ctx blame commit <sha>
ctx blame pr https://github.com/your-org/your-repo/pull/42

Like ctx indexing and search capabilities, blame runs locally, so your code and history never leave your machine.

Learn how to use Blame, including supported inputs, evidence limits, and local indexing.

Map your codebase

Graphify started with a great idea and became popular fast. The problem is that its Python/NetworkX architecture does not scale well. It installs about 30 direct dependencies, and the CLI reloads the entire graph into memory for every query. On a large repo, that can make each search slow enough to drag down an agent’s entire task.

ctx graph is a rewrite in Rust. It keeps the graph indexed in SQLite, so searches query the database directly and updates only touch changed files. Static indexing and search run as one native binary with no Python environment, API key, model, or background service.

If you aren’t familiar with Graphify, it’s like a local version of Sourcegraph: it builds a graph of your codebase and docs so an agent can ask who calls something, what depends on it, and what might break if it changes.

You might not need ctx graph or Graphify for a smaller project. Agents are surprisingly good at getting around a codebase using normal read and search tools. On a larger project, ctx graph gives them a much faster way to follow relationships across files instead of spending tokens repeatedly searching the repository.

If you train coding models, try giving ctx graph to the agents in your rollouts.

Try it

From any project:

ctx graph index .
ctx graph stats
ctx graph search authenticate

Replace authenticate with a symbol from your project, then copy its exact ID into an impact query. That shows the symbol, the code that depends on it, and the relationship between them:

$ ctx graph impact 'python:src/auth.py:authenticate@64'
Generation 1 (indexed snapshot)
python:src/auth.py:authenticate@64  function  authenticate  src/auth.py:4
python:src/auth.py:login@136         function  login         src/auth.py:7
python:src/auth.py:login@136 --calls--> python:src/auth.py:authenticate@64

ctx graph saves the graph at .graf/index.db. After changing code, update only what changed:

ctx graph update

Use --json for structured output and an exact node ID when a name is ambiguous. The usage guide covers callers, callees, paths, filters,