Search Local Coding Agent History with the ctx CLI

The longer you run coding agents, the more useful context fragments across sessions: yesterday’s failure investigation, rejected designs, exact commands, and test outcomes. A fresh chat can see the current repository, but it rarely recovers the reasoning that led there.

📑Table of Contents

1. What ctx is at a glance
2. The problem ctx solves
3. Setup and essential commands
4. Supported agents vs memory-style tools
5. Operational risks and safer defaults
6. Adoption checklist (reader next actions)
7. FAQ
8. Summary

The tool in brief

ctx (GitHub: ctxrs/ctx, ctx.rs) is an open-source local CLI that does not add a hosted memory SaaS. Instead, it normalizes agent transcripts already on your machine into local SQLite and makes them searchable. This article covers the problem it solves, a shortest-path setup, supported harnesses, how it differs from memory and graph tools, operational risks, and a practical adoption checklist.

---

Learning goals

---

What ctx is at a glance

Core specs

ctx is a Rust local CLI released under Apache-2.0. The official README describes a design that does not require a background daemon, model APIs, or API keys, and that does not send prompts or transcripts to the cloud by default. The index stays on the machine; operator write-ups often cite ~/.ctx as the default data root.

---

Spec summary

Item	Detail
Type	Local CLI (Rust + SQLite)
License	Apache-2.0
Install	curl -fsSL https://ctx.rs/install | sh (Windows: install.ps1)
Data location (reported)	Local index such as ~/.ctx
Token efficiency example	Structured search ~917 vs raw logs ~45,734 (~50x, workload-dependent)
Cloud sending	Default local; no API key claimed
Main risks	Paths/secrets may land in the index; machine-wide import can mix repos

---

Sources and how to read the numbers

Sources (as of July 2026):

• ctxrs/ctx README
• lab.main.jp write-up
• TechTimes
• Zenn FLINTERS

Treat the “~50x” figure as an example against dumping raw transcripts, not a universal benchmark. For adoption decisions, prioritize “can I recover prior evidence?” over headline token savings.

---

The problem ctx solves

Problem framing and data flow

ctx is not primarily “add persistent memory.” It turns existing agent transcripts into a searchable context asset.

Agents can inspect the current repo, yet they struggle to reuse prior decisions, failed attempts, commands, and test outcomes from earlier sessions. That is the problem framing in the official README.

The flow is:

• Inputs: local histories from each harness (for example Claude Code JSONL under ~/.claude/projects/)
• Processing: after discovery and import, sessions, events, metadata, and touched-file signals are normalized into SQLite
• Outputs: ranked hits plus show reconstruction around session/event IDs

---

Practical uses

On Hacker News Show HN, one operational story describes recognizing a disk-full CI runner failure from prior history and jumping straight to a cleanup runbook. Other uses include lighter session transcripts for PR context and reviewing agentic SDLC weaknesses across a repo’s history.

The appeal is a low-friction path to “where was yesterday’s session?” without another SaaS. At the same time, TechTimes relays a useful caution: treat history as anthropology—what happened—not automatic ground truth.

---

Setup and essential commands

Shortest path

The shortest path is install → ctx setup → ctx search → then show / optional skill wiring.

1. Install on macOS / Linux / FreeBSD: curl -fsSL https://ctx.rs/install | sh
2. Windows: irm https://ctx.rs/install.ps1 | iex
3. Index: ctx setup (create data root; discover/import known providers)
4. Inspect: ctx status / ctx sources (check importable sources with ctx sources --format json)
5. Search: ctx search "failed migration"

---

Lookup and integration commands

6. File-scoped: ctx search --file path/to/file
7. Detail: ctx show event <id> --window 3 / ctx show session <id>
8. Advanced: read-only ctx sql "...", local docs via ctx docs ..., and ctx upgrade check when installer-managed
9. Agent integration examples: npx skills add ctxrs/ctx and harness-specific skill/plugin docs

---

Setup caveats

Source

Caveats:

• Source builds or package-manager installs may be unmanaged and will not self-update like installer-managed binaries
• Review paths and secret-looking strings before sharing output externally
• Start on a personal workstation, run a few real failure keywords through search, and only then decide on skill integration

---

Supported agents vs memory-style tools

Supported harnesses

ctx’s differentiator is cross-harness local history search. The README support table includes Claude Code, Codex, Cursor, Pi, GitHub Copilot CLI, OpenCode, Gemini CLI / Antigravity, Factory AI Droid, Hermes Agent, Windsurf, Cline/Roo, and more. On a real machine, verify importable sources with ctx sources --format json.

---

Comparison table

Compare tools by inputs and outputs.

---

Inputs and strengths

Lens	ctx (history search)	Agent memory (summaries/vectors)	Repo graph tools
Primary input	Existing agent transcripts	Extracted facts/preferences/summaries	Current code structure
Strength	Recover decisions, failed commands, rejected options in original context	Stable preferences and long-lived facts	Navigate symbols and dependencies now

---

Weaknesses and fit

Lens	ctx (history search)	Agent memory (summaries/vectors)	Repo graph tools
Weakness	Raw data (and secrets) can remain in the index	Source prose thins out	Conversation “why” is missing
Cloud posture	Local by default	Product-dependent	Often local analysis
Best fit	Recurring incidents, pre-PR narrative, SDLC retrospectives	Persona/settings continuity	Large-codebase navigation

---

Comparison sources

Sources:

• ctxrs/ctx comparison notes
• TechTimes (July 2026)

---

When to combine tools

The ~50x token example contrasts structured retrieval with raw log dumps. ctx is not a drop-in replacement for memory products; evaluate it as an evidence and search layer you may combine with other tools. Adjacent layers include graph-oriented context compression (for example codebase-memory-mcp) and IDE-side conversation search (for example Cursor Side Chats).

---

Operational risks and safer defaults

Key risks

Local-only does not mean risk-free. Aggregation of sensitive material and search scope both matter.

Key risks:

• Absolute paths, secrets, and tokens in transcripts can enter the index (official README)
• Machine-wide setup can surface other repositories unintentionally; FLINTERS reported ~180k events / ~1GB in one demo and internal caution toward personal use first
• Persisting Claude Code history that would otherwise expire under cleanupPeriodDays (default 30 days) changes retention policy
• History should be treated as a record of what happened, not automatic truth

---

Practical guards

Practical guards:

1. Visually review show output before PR attachments or external sharing
2. Check index location and permissions on shared machines or CI runners
3. Decide retention, target harnesses, and exclusion paths before team rollout
4. Start on a personal workstation: setup, then three representative queries for precision

Searchability is the value; the index behaves like private source history. Name the convenience-versus-leakage tradeoff before rollout.

---

Adoption checklist (reader next actions)

Before you try

Try ctx when most of the following are true. If they are not, define retention policy first.

• ✓ You regularly use supported harnesses (Claude Code / Codex / Cursor, etc.) with local history retained
• ✓ You already re-investigate the same failures or reuse rejected options
• ✓ You want to start without extra SaaS or API keys
• ✓ You accept that paths/secrets may enter the index and you can review before sharing
• ✓ Personal-machine scope is acceptable for now (or you can explain cross-repo search scope)

---

Three steps to run today

1. Official install → ctx setup
2. Run ctx search three times with real incident/work keywords
3. Confirm hits with show, then decide only whether skill integration is worth it

Defer or hold if you only use shared CI, always mix high-sensitivity secrets into transcripts, or lack a retention policy. Sometimes the better next step is broader context-design work, not only history search.

---

FAQ

Q1. Does ctx send history to the cloud?

A. The official README states prompts, transcripts, and the index stay local and that no model API/API key is required. Local index sensitivity is a separate issue.

---

Q2. How is this different from agent memory tools?

A. Memory tools favor compact facts via summaries/vectors. ctx searches past transcripts at session/event granularity so you can return to original evidence (official comparison).

---

Q3. Which agents are supported?

A. The README lists Claude Code, Codex, Cursor, Copilot CLI, OpenCode, Gemini CLI, Hermes Agent, and many others. Confirm importable sources with ctx sources --format json.

---

Q4. Does Windows work?

A. Official docs provide a PowerShell one-liner (install.ps1). Check current releases/docs for platform specifics.

---

Q5. Is the ~50x token reduction always true?

A. It is one official example (917 vs 45,734). Results vary by query and corpus; read it as contrast with raw full-log retrieval.

---

Q6. Is team sharing OK?

A. Default posture is a private local index. Review outputs before PR/external sharing (official and lab.main.jp). FLINTERS reports internal preference for personal use first.

---

Related articles:

• 13580
• 13621
• 13623

Summary

• ctx makes existing coding-agent history locally searchable; it is not mainly “add memory”
• Shortest path: install → ctx setup → real queries with search / show
• Differentiation is multi-harness coverage and returning to original evidence—not replacing memory/graph stacks
• Next action: set up on a personal machine, validate with three representative queries (failure, migration, design debate), then consider skill integration only if useful; keep sharing review-gated

Primary links: GitHub ctxrs/ctx / ctx.rs