ctx Local Agent History Search
Search local coding-agent history for prior decisions, commands, and failed attempts.
What does this agent do, and when should you use it?
ctx is an open-source Rust CLI for fast search across coding-agent sessions already stored on a machine. It discovers supported local history sources, imports persisted records, and stores normalized session, event, and touched-file metadata in a local SQLite index. Agents query the index from the command line and receive ranked matches, snippets, and ctx IDs that can be used to inspect the underlying event or session. It runs locally without a background service, model API calls, or API keys. It fits development teams that need evidence from earlier agent work before repeating investigations or implementation attempts.
Run ctx setup to index existing local agent sessions. Use ctx search "failed migration" for natural-language history search, ctx search --file crates/foo/src/lib.rs to search sessions or events that touched a file, or ctx search --term "failed migration" --term rollback --term "cursor rename" for multiple terms. Results include matching sessions, snippets, and ctx IDs; ctx show event <ctx-event-id> --window 3 prints the relevant portion of a transcript, while ctx show session <ctx-session-id> prints a compact original session. ctx sql "SELECT provider, COUNT(*) AS sessions FROM ctx_sessions GROUP BY provider" supports read-only queries over the local index. The installed binary also includes ctx docs, ctx docs man --print ctx, ctx upgrade status, and ctx upgrade check.
- A Codex user debugging a failed migration searches prior sessions for the command output and rollback discussion before trying the change again.
- An engineer maintaining a long-lived Rust repository or multiple worktrees searches by file path to find earlier agent work that touched an implementation file.
- A developer taking over a task uses a ctx ID to inspect why a previous agent rejected a refactoring approach.
- A developer who uses Claude Code, Cursor, Pi, or GitHub Copilot CLI consolidates importable local histories into one searchable index.
- A developer auditing accumulated local sessions uses read-only SQL to count indexed sessions by provider.
What are this agent's strengths and limitations?
- Keeps retrieval tied to source sessions and events, so a match can be verified against the original transcript instead of relying only on a summary.
- Normalizes local histories into SQLite and supports natural-language, file-based, multi-term, and read-only SQL retrieval.
- Runs locally with no background service, model API call, or API-key requirement, while remaining scriptable through a CLI.
- Documents support for many agent-history sources and provides skill-install paths for Codex, Claude Code, and Cursor.
- Its usefulness depends on having discoverable, importable local agent history; `ctx sources --json` is needed to confirm the machine's actual sources.
- Transcript text is preserved and does not redact local paths or secret-shaped strings, so copied output requires review before external sharing.
- It searches prior sessions rather than providing a current-codebase map of files, symbols, imports, folders, and relationships.
- Signed self-upgrades apply only to installer-managed binaries; source builds and package-manager installs do not self-upgrade.
How do you install or deploy this agent?
On macOS, Linux, and FreeBSD: curl -fsSL https://ctx.rs/install | sh. On Windows PowerShell: irm https://ctx.rs/install.ps1 | iex. Then run ctx setup to initialize local storage and index discovered history. No API key or cloud credential is documented. The official installer downloads a binary over the network; subsequent search operates against the local SQLite index.
How do you use this agent?
Start with ctx setup. Search with ctx search "failed migration", or target a file with ctx search --file crates/foo/src/lib.rs. Use a result's ID with ctx show event <ctx-event-id> --window 3 or ctx show session <ctx-session-id> to inspect the original context. Run ctx sources --json to see which local sources are currently importable.
How does this agent compare with similar options?
Compared with agent-memory tools that save compact facts, summaries, vectors, or graph nodes, ctx is positioned for evidence that must be traced back to the original decision, command failure, or rejected approach. Compared with Graphify-style codebase graph tools, it searches prior agent sessions explaining what happened during repository changes rather than mapping the repository's current files, symbols, and relationships. The README also contrasts it with grep or raw log search through structured, ranked, cited retrieval.