ctx Local Agent History Search
Search local coding-agent history for prior decisions, commands, and failed attempts.
- Source repo
- ctxrs/ctx
- Stars
- ★ 1.2k
- Last updated
- 1d ago
- License
- Apache-2.0
- Primary language
- Rust
- FA score
- 61/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A Codex user debugging a failed migration searches prior sessions for the command output and rollback discussion before trying the change again.
- Not a fit if
- Teams that need a map of the current codebase's files, symbols, and relationships
- Users whose machines have no discoverable local agent history to import
- Teams that need transcripts automatically redacted before external sharing
- Source review
- 61/100 · Some gaps
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.
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.
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 --jsonis 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 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.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| ctx Local Agent History Search This agent | 61 · Some gaps | CLIFree | ★ 1.2k | 1d ago | Rust | Codex · Claude Code |
| Puppetmaster | 68 · Some gaps | CLIFree + model costs | ★ 471 | 12d ago | Python | Codex · Claude Code |
| AgenC Core | 74 · Some gaps | CLIFree + model costs | ★ 108 | today | TypeScript | — |
| myc Local Agent Memory | 87 · Good | CLIFree | ★ 14 | 18d ago | TypeScript | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence: README explicitly states local indexing, no cloud sending, no model APIs, no API keys, no repo writes; SECURITY.md defines security boundary and local data handling; Cargo.toml pins dependencies and uses patch. Deductions: user confirmation mechanism not explicit (e.g., before import), external effects (like self-update) not detailed, rollback mechanism not mentioned.
Evidence: README and SECURITY.md consistent, Cargo.toml pins versions, test files exist (e.g., mcp_attribution_conformance_test.py). Deductions: no specific failure message examples, dependency availability not verified (static review).
Evidence: README lists many supported agent harnesses, multiple install methods, clear documentation structure. Deductions: capability boundaries not explicit (e.g., unsupported features), trigger precision (e.g., search query exactness) not detailed.
Evidence: README provides install instructions, examples, doc links, LICENSE is Apache-2.0, Cargo.toml has version info. Deductions: no CHANGELOG, version number not explicit, maintenance responsibility not clear (no contribution guide or maintainer mention).
Evidence: README claims token efficiency, provides search examples, output format clear (JSON). Deductions: no performance benchmarks or cost comparison data, marginal value not quantified.
Evidence: Claims in README and SECURITY.md traceable, test files exist, but no independent verification. Deductions: cross-source corroboration insufficient (only internal docs), fact-inference separation not explicit.
- Static review, no code execution, all scores based on file contents.
- User confirmation mechanism not explicit, may import history without prompt.
- Self-update feature may have external effects, use with caution.
- No rollback mechanism provided, data corruption may be unrecoverable.
- Dependencies pinned but availability not verified.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
Released: 2026-11-05 Fixed - Broad multi-word searches run about 40 to 50 percent faster on large histories and return the same best matches. - While background indexing catches Blame up with newer history, Blame tells you to check ctx status and retry instead of starting another full import. - Retrying an interrupted search index rebuild removes abandoned build files before starting again, while keeping searchable history and files still in use. - ctx status no longer briefly reports a stale daemon lock while the daemon is starting or updating it. …View on GitHub ↗ -
Release notes excerpt
Released: 2026-11-04 Added - Prime Agent is a supported history provider, separate from Pi. ctx discovers version 3 sessions in the selected Prime directory, RLM child sessions, and T3 Code's local Prime session store. - Search and show preserve conversation and custom messages, Python tool calls and results, and session relationships. Explicit imports accept --provider prime-agent --path PATH; prime and prime_agent are aliases. …View on GitHub ↗ -
Release notes excerpt
Released: 2026-10-25 Added - Restored conversations show the archive creator's origin and view in search, detail and locate output, with optional archive_provenance in JSON and MCP. Labels are creator-supplied; restore older imports again to add them. ([#1134](https://github.com/ctxrs/ctx/pull/1134), [#1123](https://github.com/ctxrs/ctx/issues/1123)) …View on GitHub ↗
FAQ
Does ctx send my prompts or transcripts to a cloud service?
Does it require an API key or background service?
Which agent histories can it import?
ctx sources --json for what is importable on a specific machine.