session-ls 0.1.0__py3-none-any.whl

session_ls/__init__.py

@@ -0,0 +1,240 @@
+#!/usr/bin/env python3
+"""session-ls - list and search session history across coding agents.
+
+Default: list every session (newest first). With a keyword: search session
+titles (first real user message). Add --full to grep full content (slow).
+
+Add a new agent by appending one entry to REGISTRY:
+(name, glob, meta-parser, user-text-extractor).
+- meta-parser(f, head) -> (cwd, started_iso) or None (started may be None
+  if the format has no timestamp; file mtime is used instead)
+- user-text-extractor(line) -> first real user message text or ''
+  ('' = keep scanning; drives the early-exit read)
+"""
+import argparse, glob, json, os, re, shutil, signal, subprocess
+from datetime import datetime, timezone
+
+signal.signal(signal.SIGPIPE, signal.SIG_DFL)
+HOME = os.path.expanduser("~")
+CACHE = os.path.join(HOME, ".cache", "session_ls_cache.json")
+
+def _injected(t):
+    """True if this user message is injected context, not the user's own text."""
+    t = t.lstrip()
+    return t.startswith("<") or "AGENTS.md instructions" in t
+
+# ---- user-text extractors: line -> first real user text or '' --------------
+
+def _pi_user(line):
+    m = json.loads(line).get("message", {}) or {}
+    if m.get("role") != "user":
+        return ""
+    t = " ".join(p.get("text", "") for p in m.get("content", [])
+                 if p.get("type") == "text").strip()
+    return t if t and not _injected(t) else ""
+
+def _codex_user(line):
+    p = json.loads(line).get("payload", {}) or {}
+    if p.get("role") != "user":
+        return ""
+    t = " ".join(c.get("text", "") for c in p.get("content", [])
+                 if c.get("type") in ("input_text", "text")).strip()
+    return t if t and not _injected(t) else ""
+
+def _claude_user(line):
+    d = json.loads(line)
+    if d.get("type") != "user":
+        return ""
+    c = d.get("message", {}).get("content")
+    t = c if isinstance(c, str) else " ".join(
+        b.get("text", "") for b in c if isinstance(b, dict) and b.get("type") == "text")
+    return t.strip()
+
+def _cursor_user(line):
+    d = json.loads(line)
+    if d.get("role") != "user":
+        return ""
+    t = " ".join(b.get("text", "") for b in d.get("message", {}).get("content", [])
+                 if isinstance(b, dict) and b.get("type") == "text").strip()
+    # strip the <timestamp>...</timestamp> / <user_query> wrappers
+    return re.sub(r"^<timestamp>.*?</timestamp>\s*", "", t).replace(
+        "<user_query>", "").replace("</user_query>", "").strip()
+
+# ---- meta-parsers: (f, head) -> (cwd, started_iso) or None ------------------
+
+def _pi(f, head):
+    h = json.loads(head[0])
+    if h.get("type") != "session":
+        return None
+    return h.get("cwd"), h["timestamp"]
+
+def _codex(f, head):
+    h = json.loads(head[0])
+    p = h.get("payload", {}) if h.get("type") == "session_meta" else None
+    if not p:
+        return None
+    return p.get("cwd"), p.get("timestamp") or h.get("timestamp")
+
+def _claude(f, head):
+    for line in head:
+        d = json.loads(line)
+        if d.get("type") == "user":
+            return d.get("cwd"), d.get("timestamp")
+    return None
+
+def _cursor(f, head):
+    # ~/.cursor/projects/<cwd-dir>/agent-transcripts/<id>/<id>.jsonl
+    name = os.path.basename(os.path.dirname(os.path.dirname(os.path.dirname(f))))
+    if not name:
+        return "", None  # path too shallow (e.g. a fixture); cwd unknown
+    # ponytail: '-'->'/' decode is best-effort; dirs with '-' in a segment
+    # decode wrong. Only affects cwd display, harmless for search.
+    cwd = "/" + name.replace("-", "/") if not name[0].isdigit() else name
+    return cwd, None  # no timestamps in cursor transcripts; use mtime
+
+REGISTRY = [
+    # (name, glob, meta-parser, user-text-extractor)
+    ("pi",     os.path.join(HOME, ".pi/agent/sessions/*/*.jsonl"), _pi, _pi_user),
+    ("codex",  os.path.join(HOME, ".codex/sessions/*/*/*/rollout-*.jsonl"),
+     _codex, _codex_user),
+    ("codex",  os.path.join(HOME, ".codex/archived_sessions/rollout-*.jsonl"),
+     _codex, _codex_user),
+    ("claude", os.path.join(HOME, ".claude/projects/*/*.jsonl"), _claude, _claude_user),
+    ("cursor", os.path.join(HOME, ".cursor/projects/*/agent-transcripts/*/*.jsonl"),
+     _cursor, _cursor_user),
+]
+
+def collect():
+    files = []
+    for name, pattern, parse, user_text in REGISTRY:
+        for f in glob.glob(pattern):
+            if name == "cursor":
+                # keep only the main transcript, skip subagents/
+                if os.path.basename(f)[:-6] != os.path.basename(os.path.dirname(f)):
+                    continue
+            files.append((name, parse, user_text, f))
+    return files
+
+def _load_cache():
+    try:
+        with open(CACHE, encoding="utf-8") as f:
+            return json.load(f)
+    except Exception:
+        return {}
+
+def _save_cache(cache):
+    os.makedirs(os.path.dirname(CACHE), exist_ok=True)
+    tmp = CACHE + ".tmp"
+    with open(tmp, "w", encoding="utf-8") as f:
+        json.dump(cache, f, ensure_ascii=False)
+    os.replace(tmp, CACHE)
+
+def parse_all(files):
+    cache = _load_cache()
+    new_cache, dirty, rows = {}, False, []
+    for name, parse, user_text, f in files:
+        try:
+            st = os.stat(f)
+            sig = [st.st_size, st.st_mtime]
+            c = cache.get(f)
+            if c and c["sig"] == sig:  # unchanged: reuse cached metadata
+                new_cache[f] = c
+                rows.append({k: v for k, v in c.items() if k != "sig"})
+                continue
+        except OSError:
+            continue
+        try:
+            with open(f, encoding="utf-8", errors="replace") as fh:
+                head, title = [], ""
+                for _ in range(2000):
+                    line = fh.readline().strip()
+                    if not line:
+                        break
+                    head.append(line)
+                    title = user_text(line)
+                    if title:
+                        break  # title found, stop reading
+        except Exception:
+            continue
+        r = parse(f, head) if head else None
+        if not r:
+            continue
+        cwd, started = r
+        if not title:
+            for line in head[1:]:
+                title = user_text(line)
+                if title:
+                    break
+        mtime = datetime.fromtimestamp(st.st_mtime, timezone.utc).isoformat()
+        row = {"agent": name, "cwd": cwd or "", "started": started or mtime,
+               "last": mtime, "title": title, "file": f}
+        new_cache[f] = {**row, "sig": sig}
+        dirty = True
+        rows.append(row)
+    if dirty:
+        _save_cache(new_cache)
+    return rows
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("keyword", nargs="?", default="",
+                    help="search session titles (first user message)")
+    ap.add_argument("-f", "--full", action="store_true",
+                    help="grep full session content (slow)")
+    ap.add_argument("-a", "--agent", help="only this agent")
+    ap.add_argument("-c", "--cwd", help="only sessions under this cwd substring")
+    ap.add_argument("--since", metavar="DATE", help="started on/after (YYYY-MM-DD)")
+    ap.add_argument("--until", metavar="DATE", help="last active on/before (YYYY-MM-DD)")
+    ap.add_argument("-n", "--limit", type=int, help="show only N newest")
+    ap.add_argument("-l", "--list", action="store_true", help="print file paths only")
+    ap.add_argument("--json", action="store_true", help="print rows as JSON lines")
+    args = ap.parse_args()
+
+    files = collect()
+
+    if args.full and args.keyword:
+        # ripgrep if available (much faster over GBs), else plain grep
+        rg = shutil.which("rg")
+        cmd = [rg, "-l", "-i", args.keyword, *[f for _, _, _, f in files]] if rg \
+            else ["grep", "-l", "-i", args.keyword, *[f for _, _, _, f in files]]
+        out = subprocess.run(cmd, capture_output=True, text=True).stdout
+        keep = set(out.splitlines())
+        files = [x for x in files if x[3] in keep]
+
+    rows = parse_all(files)
+
+    kw = args.keyword.lower()
+    if kw and not args.full:
+        rows = [r for r in rows if kw in r["title"].lower()]
+    if args.agent:
+        rows = [r for r in rows if r["agent"] == args.agent]
+    if args.cwd:
+        rows = [r for r in rows if args.cwd in r["cwd"]]
+    if args.since:
+        rows = [r for r in rows if r["started"][:10] >= args.since]
+    if args.until:
+        rows = [r for r in rows if r["last"][:10] <= args.until]
+
+    rows.sort(key=lambda r: r["last"], reverse=True)
+    if args.limit:
+        rows = rows[:args.limit]
+
+    if args.json:
+        for r in rows:
+            print(json.dumps(r, ensure_ascii=False))
+    elif args.list:
+        for r in rows:
+            print(r["file"])
+    else:
+        print(f"{'AGENT':<7} {'STARTED':<20} {'LAST':<20}  "
+              f"{'CWD':<42} TITLE")
+        print("-" * 130)
+        for r in rows:
+            cwd = r["cwd"] or r["file"]
+            print(f"{r['agent']:<7} {r['started'][:19]:<20} {r['last'][:19]:<20}  "
+                  f"{cwd[:42]:<42} {r['title'][:60]}")
+        print(f"\n{len(rows)} sessions")
+
+if __name__ == "__main__":
+    main()

session_ls/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from session_ls import main
+
+if __name__ == "__main__":
+    sys.exit(main())

session_ls-0.1.0.data/data/share/man/man1/session-ls.1

@@ -0,0 +1,150 @@
+.TH SESSION-LS 1 "August 2026" "session-ls 0.1.0" "User Commands"
+.SH NAME
+session-ls \- list and search session history across coding agents
+.SH SYNOPSIS
+.B session-ls
+[\fIKEYWORD\fR] [\fIOPTIONS\fR]
+.SH DESCRIPTION
+.B session-ls
+scans the local session stores of coding agents (pi, codex, claude,
+cursor) and lists every session, newest first.  Each line shows the
+agent, session start time, last activity, the working directory, and
+the first real user message (the session "title").
+
+Given a
+.IR KEYWORD ,
+only sessions whose title contains it (case-insensitive substring
+match) are shown.  With
+.B \-f
+the keyword is instead matched against the full session content.
+
+.B session-ls
+is a plain local command-line tool.  It keeps no index and does no
+semantic processing; matching is literal text comparison.  Session
+files are read directly from the agent stores.  Parsed metadata is
+cached in
+\fI~/.cache/session_ls_cache.json\fR ,
+keyed by file size and modification time, so repeated runs over
+gigabytes of session logs are fast; the cache is rebuilt automatically
+whenever a file changes.
+.SH OPTIONS
+.TP
+.B KEYWORD
+Search term.  Matched case-insensitively against session titles (or,
+with
+.BR \-f ,
+against full session content).  Multiple words must be quoted; they are
+matched as one phrase.
+.TP
+.B \-f, \-\-full
+Search the full session content instead of titles only.  Uses ripgrep
+if available, otherwise plain grep; this can take a few seconds over
+large session stores.
+.TP
+.B \-a, \-\-agent \fIAGENT\fR
+Only show sessions from this agent.  Valid values: pi, codex, claude,
+cursor.
+.TP
+.B \-c, \-\-cwd \fISUBSTRING\fR
+Only show sessions whose working directory contains SUBSTRING.
+.TP
+.B \-\-since \fIDATE\fR
+Only show sessions started on or after DATE (YYYY\-MM\-DD).
+.TP
+.B \-\-until \fIDATE\fR
+Only show sessions last active on or before DATE (YYYY\-MM\-DD).
+.TP
+.B \-n, \-\-limit \fIN\fR
+Show only the N most recently active sessions.
+.TP
+.B \-l, \-\-list
+Print only the session file paths, one per line (useful for piping to
+other commands).
+.TP
+.B \-\-json
+Print matching sessions as JSON Lines, one object per line, with keys:
+agent, cwd, started, last, title, file.
+.TP
+.B \-h, \-\-help
+Show usage and exit.
+.SH EXIT STATUS
+.B session-ls
+returns 0 on success.  No session files found is not an error.
+.SH FILES
+.TP
+.I ~/.pi/agent/sessions/*/*.jsonl
+pi session store, one directory per working directory.
+.TP
+.I ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl
+codex session store, grouped by date.
+.TP
+.I ~/.codex/archived_sessions/rollout-*.jsonl
+codex archived sessions.
+.TP
+.I ~/.claude/projects/*/*.jsonl
+claude code session store, one directory per project.
+.TP
+.I ~/.cursor/projects/*/agent-transcripts/*/*.jsonl
+cursor agent transcripts (subagent transcripts are ignored).
+.TP
+.I ~/.cache/session_ls_cache.json
+metadata cache.  Safe to delete; it is rebuilt on the next run.
+.SH ENVIRONMENT
+.TP
+.B HOME
+Determines where agent stores and the cache are looked up.
+.SH EXAMPLES
+List the ten most recent sessions:
+.PP
+.RS
+.nf
+session-ls -n 10
+.fi
+.RE
+.PP
+Find sessions whose first user message mentions a LAN (title search):
+.PP
+.RS
+.nf
+session-ls websocket
+.fi
+.RE
+.PP
+Search the full content of all sessions for a phrase:
+.PP
+.RS
+.nf
+session-ls "immich 2283" -f
+.fi
+.RE
+.PP
+Find pi sessions in a project started this month, as JSON:
+.PP
+.RS
+.nf
+session-ls -a pi -c nemo -f --since 2026-08-01 --json
+.fi
+.RE
+.PP
+List file paths of matching sessions and show their first lines:
+.PP
+.RS
+.nf
+session-ls websocket -l | xargs head -1
+.fi
+.RE
+.SH NOTES
+The title of a session is the first real user message.  Sessions whose
+log starts with injected context (for example codex
+<recommended_plugins> or AGENTS.md instructions blocks) skip that
+context and use the first genuine user message instead; if a session
+contains only injected context, the first user message is shown anyway.
+Cursor transcripts carry no timestamps, so their start time equals the
+file modification time.  The cursor working directory is decoded from
+the project directory name (dashes become slashes) and may be imprecise
+for paths containing dashes; this affects display only, never search.
+.SH SEE ALSO
+.BR rg (1),
+.BR grep (1)
+.SH AUTHOR
+The session-ls project

session_ls-0.1.0.dist-info/METADATA

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: session-ls
+Version: 0.1.0
+Summary: List and search session history across coding agents (pi, codex, claude, cursor)
+License: MIT License
+        
+        Copyright (c) 2026 4ier
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Repository, https://github.com/4ier/session-ls
+Project-URL: Issues, https://github.com/4ier/session-ls/issues
+Keywords: agent,sessions,search,pi,codex,claude,cursor
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# 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 uses `ripgrep` when
+  available (fallback: `grep`).
+- **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, one module.
+- **Extensible.** Adding another agent is one `REGISTRY` entry plus two
+  small functions (see below).
+
+## Install
+
+```bash
+pip install .            # from a checkout
+pipx install .           # recommended: isolated environment
+```
+
+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]
+```
+
+| Option | Meaning |
+| --- | --- |
+| `KEYWORD` | search titles (first user message), case-insensitive substring |
+| `-f, --full` | search full session content instead of titles (slow, uses rg/grep) |
+| `-a, --agent` | only this agent: `pi`, `codex`, `claude`, `cursor` |
+| `-c, --cwd` | only sessions under a cwd substring |
+| `--since DATE` | started on/after (YYYY-MM-DD) |
+| `--until DATE` | last active on/before (YYYY-MM-DD) |
+| `-n, --limit N` | show only the N newest |
+| `-l, --list` | print file paths only (for piping) |
+| `--json` | JSON Lines output (keys: agent, cwd, started, last, title, file) |
+
+### Examples
+
+```bash
+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
+
+| Agent | Store | Timestamps |
+| --- | --- | --- |
+| pi | `~/.pi/agent/sessions/<encoded-cwd>/*.jsonl` | in file |
+| codex | `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl` (+ `archived_sessions/`) | in file |
+| claude | `~/.claude/projects/<encoded-cwd>/*.jsonl` | in file |
+| cursor | `~/.cursor/projects/*/agent-transcripts/<id>/<id>.jsonl` | file mtime (none in file) |
+
+## 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)
+
+```python
+REGISTRY = [
+    # (name, glob, meta-parser, user-text-extractor)
+    ("myagent", os.path.join(HOME, ".myagent/sessions/*.jsonl"),
+     _myagent_meta, _myagent_user),
+]
+```
+
+## Development
+
+```bash
+python -m pytest tests/        # plain asserts, also runnable via pytest
+python -m session_ls ...       # run from a checkout
+```
+
+## License
+
+MIT

session_ls-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+session_ls/__init__.py,sha256=XbLVNLla-VrE6MHVIqj0R7yXlzhvMav5Ows0DO4QO6g,9225
+session_ls/__main__.py,sha256=cnpZbFHpPCgpmujpXbXsrftEyMgJ82tyfyrhjryrYFw,89
+session_ls-0.1.0.data/data/share/man/man1/session-ls.1,sha256=HLszUlPWfIj7gkkXh1hvMu1ZS9LMk1qDxQsNsGPyGfY,4255
+session_ls-0.1.0.dist-info/licenses/LICENSE,sha256=cYZ3LVkc_-w5u7NQqO4QjWZ6Z9daosrMOOrb5IOXdeI,1061
+session_ls-0.1.0.dist-info/METADATA,sha256=5V07kV-YypVv81h1R3FbgX1o4s8_i9wYaKYXwWqkFI8,5741
+session_ls-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+session_ls-0.1.0.dist-info/entry_points.txt,sha256=c3-N-I3_s9kzXBiSKfHMTBr4KgwcPfI3g1sTsHgfpj0,47
+session_ls-0.1.0.dist-info/top_level.txt,sha256=StBVKOP2cfg1Diwy5KCoxUg_ZPshgQrWLLxdkgkpDz8,11
+session_ls-0.1.0.dist-info/RECORD,,

session_ls-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

session_ls-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+session-ls = session_ls:main

session_ls-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 4ier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

session_ls-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+session_ls