README.md
August 1, 2026 ยท View on GitHub
ctx is an open-source CLI for fast local search across your past coding agent sessions.
Coding agents usually start from zero. They can inspect the current repo, but they often cannot recover the discussions, decisions, failed attempts, commands, and test results from earlier work.
Those sessions are full of useful context:
- decisions, constraints, intent, and rejected approaches from you
- bug investigations, refactors, file paths, commands, patches, and notes from previous agents
ctx imports those logs into a self-contained local Core generation, then gives current and future agents a CLI for finding the prior discussion, command, or failed attempt before they repeat it.
Install and set up ctx
macOS, Linux, and FreeBSD:
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)
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.
How it works
Your past agent sessions are stored in local provider history files. ctx discovers supported sources, imports the real persisted records, and publishes normalized content, session and event identities, and touched-file metadata into self-contained local Core generations.
ctx is written in Rust. A local lexical index, optional semantic index, and read-only SQLite metadata projection keep retrieval fast and scriptable; ctx show reads the same active Core generation.
The data root is local and private by default. Transcript text is preserved rather than hiding local paths or secret-shaped strings, so review copied output before sharing it outside the machine.
# 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/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"
# Advanced: inspect the local metadata projection with read-only SQL
ctx sql "SELECT provider, COUNT(*) AS sessions FROM ctx_sessions GROUP BY provider"
# 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>
Those IDs let your current agent recover as much context from previous sessions as it needs.
ctx does not send your prompts, transcripts, or indexed history to a cloud service, call model APIs, require API keys, or write into your source repositories.
The installed binary also includes local docs and man-page generation:
ctx docs search "upgrade"
ctx docs show cli-reference
ctx docs man --print ctx
Official installer-managed binaries support signed self-upgrades:
ctx upgrade status
ctx upgrade check
Source builds and package-manager installs remain unmanaged and do not self-upgrade.
For the full pipeline, see How ctx works. For a quick first run, see Quickstart.
Supported agent histories
Support means ctx can discover or read that harness's persisted local history and import it into a local Core generation. Use ctx sources --format json on your machine to see which sources are currently importable.
| Agent harness | Support |
|---|---|
| Claude Code | Supported |
| Codex | Supported |
| Cursor | Supported |
| Pi | Supported |
| GitHub Copilot CLI | Supported |
| OpenCode | Supported |
| Gemini CLI / Antigravity | Supported |
| Factory AI Droid | Supported |
| OpenClaw | Supported |
| Hermes Agent | Supported |
| AstrBot | Supported |
| NanoClaw | Supported |
| Shelley | Supported |
| Auggie / Augment | Supported |
| Cline / Roo Code | Supported |
| CodeBuddy | Supported |
| Continue | Supported |
| Crush | Supported |
| Deep Agents | Supported |
| Firebender | Supported |
| ForgeCode | Supported |
| Goose | Supported |
| Junie | Supported |
| Kilo Code | Supported |
| Kimi Code CLI | Supported |
| Kiro CLI | Supported |
| Lingma | Supported |
| MiMo Code | Supported |
| Mistral Vibe | Supported |
| Mux | Supported |
| OpenHands | Supported |
| Qoder | Supported |
| Qwen Code | Supported |
| Rovo Dev | Supported |
| Tabnine CLI | Supported |
| Trae / Trae CN | Supported |
| Warp | Supported |
| Windsurf | Supported |
| Zed | Supported |
How ctx compares
Agent memory tools usually save compact facts, summaries, vectors, or graph nodes. Those can help with stable preferences, but they are weak evidence when the next agent needs to know where a decision came from, what command failed, or what was rejected in the original conversation.
Graphify-style tools answer a different question. They map the current repository: files, symbols, imports, folders, and relationships. ctx searches the prior agent sessions that explain what happened while people and agents changed that repository.
ctx keeps retrieval tied to sessions and events, so another agent can inspect the source before using it. Read more about agent memory, Graphify-style codebase graphs, and grep or log search.
Explore the docs
| Page | What it covers |
|---|---|
| Install | Install ctx, initialize local storage, and index discovered local history. |
| Quickstart | Search local history, inspect an event, open the session, and use JSON output. |
| Install the ctx skill | Install the agent-history search skill with the open skills installer. |
| Package managers and unmanaged installs | Install from GitHub Releases, mise, Homebrew, or source builds. |
| Agent plugin installs | Install the ctx skill through Codex, Claude Code, Cursor, or a raw skill folder. |
| SDKs | Use ctx agent history search from TypeScript, Python, Rust, Go, JVM, Swift, or .NET code. |
| Custom history plugins | Build an advanced local adapter for agent formats ctx does not support natively. |
| Cursor | Import Cursor agent transcripts and ask Cursor to cite retrieved local history before editing. |
| How it works | Understand discovery, import, SQLite storage, search refresh, and cited retrieval. |
| Supported agents | See which agent histories ctx can discover, import, and search today. |
| CLI reference | Review setup, status, sources, import, show, search, SQL, MCP, and doctor. |