session-ls

List and search session history across all coding agents on your machine: pi, codex, claude, cursor.

$ session-ls -n 3
AGENT   STARTED              LAST                  CWD                            TITLE
codex   2026-07-29T00:03:17  2026-07-29T00:21:15   /home/alice/projects/website   fix the login redirect loop
pi      2026-07-17T14:42:45  2026-07-18T08:45:13   /home/alice/projects/backend   tune the postgres connection pool
claude  2026-06-15T03:08:57  2026-06-15T03:31:55   /home/alice/dotfiles           migrate to starship prompt

Sessions are read directly from each agent's local store, newest first. The title of a session is the first thing the person actually typed. Injected context (plugin lists, AGENTS.md, environment blocks, image wrappers, slash-command echoes) is skipped part by part, and wrapped requests are unwrapped: Codex desktop's ## My request:, a thread goal's <objective>, and chat bridges' <user_input>.

Design

• Fast. Metadata is cached in ~/.cache/session_ls_cache.json, keyed by file size + mtime; unchanged files are never re-read. Listing ~1000 sessions takes milliseconds. Full-text search streams literal matches and decoded JSON Unicode text. A long-lived HistoryIndex rescans only what changed: unchanged directories keep their listings and unchanged files their records (every file is still lstated).
• Plain search, no semantics. No index, no embeddings, no network. Matching is literal substring comparison. Decide what's relevant yourself - or hand the file paths to an LLM.
• Lightweight, zero dependencies. Pure stdlib: a legacy session-ls CLI, and a versioned typed API (session_ls.api) for programs such as 4top.
• Extensible. Adding another agent is one REGISTRY entry plus two small functions (see below).

Install

uv tool install session-ls   # or:
pipx install session-ls      # isolated environment
pip install session-ls       # into the current environment
pip install -e '.[dev]'      # from a checkout, to work on it

Requires Python >= 3.9. A man page (session-ls(1)) is installed alongside; on macOS venvs, point MANPATH at the venv's share/man to see it.

Usage

session-ls [KEYWORD] [OPTIONS]

Examples

session-ls -n 10                              # ten most recent sessions
session-ls websocket                              # title search
session-ls "immich 2283" -f                  # full-content search
session-ls -a pi -c nemo --since 2026-08-01   # filters combine
session-ls websocket -l | xargs head -1          # inspect raw matches
session-ls websocket --json | jq -r .file        # feed paths to other tools

Supported agents

Adding an agent

Append an entry to REGISTRY in src/session_ls/__init__.py:

1. a glob of session files
2. meta_parser(f, head) -> (cwd, started_iso) | None
3. user_text(line) -> first real user text | '' (drives the early-exit read)

REGISTRY = [
    # (name, glob, meta-parser, user-text-extractor)
    ("myagent", os.path.join(HOME, ".myagent/sessions/*.jsonl"),
     _myagent_meta, _myagent_user),
]

Agent skill

For AI agents (pi et al.), skills/session-ls/SKILL.md is a ready-to-install skill: when to use session-ls, common flag combos, and how to pipe results into a read of the underlying session files. Copy skills/session-ls into your agent's skills directory to enable it.

Development

python -m pytest tests/        # plain asserts, also runnable via pytest
python -m session_ls ...       # run from a checkout

License

MIT

0.2 API

session_ls.api exposes explicit Root, HistoryIndex, HistoryRecord, search_full, and excerpt objects. Inject roots/cache/host identity rather than changing process-global HOME. The legacy command still emits the same six JSON fields. Package imports do not change SIGPIPE. No TUI dependencies are required.

HistoryRecord.subagent is true for a session another agent session started for itself (Codex thread_spawn workers and the guardian approval reviewer), and HistoryRecord.parent is the spawning session's native id when the child names it. Both default to "not a subagent". HistoryRecord.scripted is true for a session started with no person at a prompt (claude -p or the Claude Agent SDK, codex exec or the Codex SDK; Pi records no such marker).

In the API, a first message too short to say anything (at most 8 terminal columns once whitespace is collapsed: "hi", "pwd", "exit", or nothing) gives way to the session's own name when it has one: Claude's latest rename, else its generated title, else its agent name; Pi's session name; Codex's thread name from session_index.jsonl. The session-ls command keeps the first message.