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 its first real user message (injected context such as codex <recommended_plugins> or AGENTS.md instructions is skipped).

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.
• 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.