shlog is a local-first CLI for searching your agent session history — Codex, Claude Code, and Pi transcripts. It's built for agents (and humans) that investigate: find the right session first, then read only the relevant range.
Agent sessions accumulate fast. When you need to recall a past decision, debug a configuration, or recover context from last week's work, shlog lets you search across sessions without opening each transcript by hand. It indexes your session logs into a local SQLite database with full-text search, and gives you progressive retrieval: metadata scan → candidate search → targeted read.
curl -fsSL https://github.com/catoncat/sherlog/releases/latest/download/install.sh | shOr via Homebrew:
brew tap catoncat/sherlog
brew install sherlogThe installer places shlog in $HOME/.local/bin, verifies SHA-256, and never runs sudo. Set SHLOG_INSTALL_DIR to pick another directory. Upgrading from 0.4.x? Run shlog sync once to migrate your index.
Prebuilt archives for macOS (arm64 only) and Linux (x64 GNU). Node.js is not required to run Sherlog.
brew update
brew upgrade catoncat/sherlog/sherlog
shlog --version
shlog sync --source codexVersion 0.5.4 reads both legacy and current Codex conversation records. The first sync after upgrading automatically replays outdated projections, including files previously indexed as empty. No index deletion is needed. Project-scoped and custom-root users should keep their existing --cwd, --root, and --db options.
Paginated Codex continuations are independently searchable segments. Use the returned sessionRef to read each segment. For archived plain JSONL history, sync and search that directory explicitly with --root; registering a cold root only protects existing projections from prune. Compressed Codex cold files are retained, not reindexed.
shlog sync # index your default Codex sessions
shlog find "health check" # search across sessions
shlog read-range <sessionRef> --seq <matchSeq> # read around a match
shlog read-page <sessionRef> --offset 0 --limit 20 # read from the topfind prints one compact block per candidate — date, source, cwd, anchor, title, digest, matched snippet — and a ready-to-run read: line. Ten results are about 2k tokens; add --json only when you need the full machine contract (evidenceRead, coverage, zeroResults), which is roughly 4–5× larger.
If find suggests a coverage gap, run the suggested sync and retry. For project-scoped work:
shlog status --cwd /Users/you/work/project --json
shlog sync --cwd /Users/you/work/project| Command | What it does |
|---|---|
status |
Show index state, source inventory, and coverage |
sync |
Index new sessions (the only command that writes to the index) |
find |
Full-text search across sessions with ranked results |
read-range |
Read a window of messages around a match |
read-page |
Read a page of messages from a session |
list |
List sessions matching filters |
stats |
Summary statistics about the index |
cold |
Manage cold storage retention (add/remove roots) |
All read commands operate on the SQLite index — they never scan raw transcripts.
Install the optional agent skill so your agent can invoke Sherlog directly:
npx skills add -g catoncat/sherlogThis uses an external skill manager; it does not add a Node.js dependency to Sherlog itself.
- Usage Guide — Full command reference, selectors, sync details, and storage.
- Design Philosophy — Why FTS? Why not ripgrep or embeddings?
- Architecture — Retrieval model and how it works.
- Roadmap — What's coming next.
See CONTRIBUTING.md and AGENTS.md.