Universal CLI for exporting and searching AI coding sessions from Codex, Claude Code, and Cursor.
harness-recall (hrc) parses local JSONL session files from AI coding tools, normalizes them into a common format, and indexes them with SQLite + FTS5 full-text search. You can list recent sessions, search across all of them, view sessions in the terminal, and export to Markdown, HTML, or JSON.
Codex, Claude Code, and Cursor are supported in v1.1. The parser interface is designed to be extended — adding Copilot or Aider support means writing one new file.
pip install harness-recallpipx install harness-recall# List recent sessions (auto-indexes on first run)
$ hrc list
ID Source Date Project Title
019cbc4c codex 2026-04-06 ~/GitHub/myapp fix auth middleware redirect loop
018fa31d claude-code 2026-04-05 ~/GitHub/myapp add docker-compose health checks
018e119a codex 2026-04-04 ~/GitHub/api-service refactor token validation logic
# Search across all sessions
$ hrc search "auth middleware"
019cbc4c codex 2026-04-06 fix auth middleware redirect loop
018c774e codex 2026-03-28 debug auth middleware CORS issue
# View a session in the terminal
$ hrc show 019cbc4c
# Export to HTML
$ hrc export 019cbc4c --format html -o ./exports/
Exported: ./exports/019cbc4c-fix-auth-middleware.html| Source | macOS | Linux | Windows | Status |
|---|---|---|---|---|
| Codex | ~/.codex/sessions/ |
~/.codex/sessions/ |
~\.codex\sessions\ |
Supported |
| Claude Code | ~/.claude/projects/ |
~/.claude/projects/ |
~\.claude\projects\ |
Supported |
| Cursor | ~/Library/Application Support/Cursor/User/globalStorage/ |
~/.config/Cursor/User/globalStorage/ |
%APPDATA%\Cursor\User\globalStorage\ |
Supported |
| Copilot | — | — | — | Planned |
Paths are auto-detected per platform. Override them in ~/.harness-recall/config.toml if your installation uses a non-standard location.
List sessions, most recent first.
hrc list # default 25 sessions
hrc list --source codex # filter by source
hrc list --after 2026-03-01 # filter by date
hrc list --project ~/GitHub/myapp # filter by project directory
hrc list --limit 50 # show more resultsFull-text search across all session content using SQLite FTS5.
hrc search "docker compose"
hrc search "auth middleware" --source codex
hrc search "fix" --tool exec_command # sessions using a specific toolPretty-print a session in the terminal using rich.
hrc show 019cbc4c # show session (tool call details collapsed)
hrc show 019cbc4c --full # include full tool call arguments and outputs
hrc show 019cbc4c --turns 1-5 # show specific turns onlySession IDs can be abbreviated — hrc show 019cbc resolves by prefix match.
Export one or more sessions to a file.
hrc export 019cbc4c # Markdown (default)
hrc export 019cbc4c --format html # styled HTML
hrc export 019cbc4c --format json # normalized IR as JSON
hrc export 019cbc4c -o ./exports/ # specify output directory
hrc export --all --format markdown # bulk export all sessions
hrc export --source codex -o ./ # export all Codex sessionsManage the SQLite index. Index updates run automatically on other commands, but you can trigger them manually.
hrc index # index new and changed sessions only
hrc index --rebuild # full re-index from scratch
hrc index --stats # show index statisticshrc browseInteractive terminal UI for browsing sessions. Features live search, session preview, source filtering, and export.
Key bindings: ↑↓/jk navigate, Enter expand, / search, e export, f filter source, q quit.
hrc statsShow session statistics: counts by source, sessions by month, top projects, models used, and token usage summary.
Show or edit configuration.
hrc configMarkdown — default format. Clean transcript with session metadata header, role labels, and fenced code blocks. Renders on GitHub and is pasteable into any document.
HTML — self-contained single file. Warm, minimal design with collapsible tool calls (<details>/<summary>), syntax-highlighted code, and automatic dark mode via prefers-color-scheme. Optionally loads Space Grotesk and JetBrains Mono from CDN; system font fallbacks work offline. No JavaScript frameworks.
JSON — the normalized intermediate representation (IR). Useful for scripting or piping into other tools.
Parsers (Codex, Claude Code, ...)
|
v
Intermediate Representation (IR)
|
v
SQLite + FTS5 Index (~/.harness-recall/index.db)
|
v
Renderers (Markdown, HTML, JSON)
Each parser reads raw JSONL from its source and emits IR objects (Session, Turn, ToolCall). Renderers and the search index only ever see IR — never raw source data. The index is built automatically on first use and updated incrementally using file modification times.
Implement BaseParser in a new file under src/harness_recall/parsers/ and register it in __init__.py.
from harness_recall.parsers.base import BaseParser
from harness_recall.ir import Session
from pathlib import Path
class MyCLIParser(BaseParser):
name = "mycli"
default_paths = ["~/.mycli/sessions/"]
file_pattern = "**/*.jsonl"
def parse(self, file_path: Path) -> Session:
# Read file_path, return a Session IR object
...The discover() method is provided by BaseParser — it globs default_paths with file_pattern. Override it if the source uses a non-standard layout.
Parser contributions are welcome. See docs/adding-a-parser.md for a full walkthrough.
harness-recall auto-detects ~/.codex/sessions/ and ~/.claude/projects/ on first run. Override paths or add custom sources in ~/.harness-recall/config.toml:
[sources]
codex = ["/custom/codex/path"]
claude-code = ["/custom/claude/path"]
[index]
db_path = "/custom/index.db"Pull requests are welcome. Parser contributions are the easiest entry point — if you use an AI coding tool that isn't supported, adding a parser is a well-defined, isolated task.
Please open an issue before starting significant work to confirm the approach.
MIT