Skip to content

Replay your coding agent sessions as a map and a timeline

feat(cli): filter listed sessions by agent and time

gezerui8889f2d65c089ed
diff --git a/README.md b/README.md
index 8528c9f..5d85cd0 100644
--- a/README.md
+++ b/README.md
@@ -192,8 +192,8 @@ agentplay agents show which agents were found on this machine
| Flag | On | Meaning |
|---|---|---|
-| `--since 30d` | build, view | only sessions changed in the window (`12h`, `2w`, `2026-09-01`) |
-| `--agents claude-code,codex` | build, view | limit to these agents |
+| `--since 30d` | build, view, list | only sessions changed in the window (`12h`, `2w`, `2026-09-01`); list uses the stored transcript modification time, or the start time for imported maps |
+| `--agents claude-code,codex` | build, view, list | limit to these agents |
| `--rebuild` | build, view | rebuild even unchanged sessions |
| `--path-mode dirs_only` | build, view | see [Privacy](#privacy) |
| `--limit N` | build, view, list | newest N sessions |
diff --git a/python/src/agentplay/cli.py b/python/src/agentplay/cli.py
index 341a485..6e0f099 100644
--- a/python/src/agentplay/cli.py
+++ b/python/src/agentplay/cli.py
@@ -239,12 +239,35 @@ def cmd_view(args: argparse.Namespace) -> int:
# --------------------------------------------------------------------------- list
def cmd_list(args: argparse.Namespace) -> int:
st = Store()
- rows = [r for r in st.rows() if r.get("role") not in ("subagent", "helper")][: args.limit or 30]
+ agents = _agents(args.agents)
+ since = _since(args.since)
+ rows = []
+ for row in st.rows():
+ if row.get("role") in ("subagent", "helper"):
+ continue
+ if agents is not None and row.get("agentTool") not in agents:
+ continue
+ if since is not None:
+ # Imported maps have no transcript mtime; use their session start.
+ changed = row.get("sourceMtime")
+ if changed is None:
+ try:
+ started = datetime.fromisoformat(row.get("startedAt") or "")
+ changed = (started if started.tzinfo else started.replace(tzinfo=UTC)).timestamp()
+ except ValueError:
+ continue
+ if changed < since.timestamp():
+ continue
+ rows.append(row)
+ rows = rows[: args.limit or 30]
if args.json:
print(json.dumps(rows, indent=2))
return 0
if not rows:
- print("No maps yet. Run `agentplay build`.")
+ if agents is not None or since is not None:
+ print("No sessions match these filters.")
+ else:
+ print("No maps yet. Run `agentplay build`.")
return 0
for r in rows:
cost = f"${r.get('costUsd') or 0:.2f}"
@@ -360,6 +383,8 @@ def parser() -> argparse.ArgumentParser:
b.set_defaults(fn=cmd_build)
ls = sub.add_parser("list", parents=[common], help="list built sessions")
+ ls.add_argument("--agents", help=f"comma-separated subset of: {', '.join(discover.AGENTS)}")
+ ls.add_argument("--since", help="only sessions changed since (30d, 12h, 2w, YYYY-MM-DD); imported maps use start time")
ls.add_argument("--limit", type=int)
ls.add_argument("--json", action="store_true")
ls.set_defaults(fn=cmd_list)
diff --git a/python/tests/test_cli_output.py b/python/tests/test_cli_output.py
index 831132e..4d13a81 100644
--- a/python/tests/test_cli_output.py
+++ b/python/tests/test_cli_output.py
@@ -3,6 +3,7 @@
from __future__ import annotations
import io
+import json
import logging
from collections import Counter
from datetime import UTC, datetime
@@ -165,3 +166,74 @@ def test_view_says_when_the_requested_port_is_busy(monkeypatch, capsys, requeste
out, err = capsys.readouterr()
assert (f"Port {requested} is busy; using {bound} instead." in err) is notice
assert f"127.0.0.1:{bound}/" in out
+
+
+def list_store(monkeypatch, tmp_path):
+ monkeypatch.setenv("AGENTPLAY_HOME", str(tmp_path))
+ monkeypatch.setattr(cli, "_TTY", False)
+ st = cli.Store()
+ recent = datetime(2026, 10, 20, tzinfo=UTC).timestamp()
+ old = datetime(2026, 9, 1, tzinfo=UTC).timestamp()
+ for sid, agent, started, modified, role in [
+ ("other", "claude-code", "2026-10-23T00:00:00Z", recent, None),
+ ("child", "codex", "2026-10-22T00:00:00Z", recent, "subagent"),
+ ("helper", "codex", "2026-10-21T00:00:00Z", recent, "helper"),
+ ("imported", "codex", "2026-10-20T01:00:00+02:00", None, None),
+ ("stale", "codex", "2026-10-19T00:00:00Z", old, None),
+ ("updated", "codex", "2026-09-01T00:00:00Z", recent, None),
+ ("old-import", "codex", "2026-08-01T00:00:00Z", None, None),
+ ("undated", "codex", "", None, None),
+ ]:
+ st.index[sid] = {"sessionId": sid, "agentTool": agent, "startedAt": started, "role": role}
+ if modified is not None:
+ st.index[sid]["sourceMtime"] = modified
+ st.save_index()
+ return st
+
+
[email protected]("as_json", [False, True])
[email protected]("since", ["7d", "168h", "1w", "2026-10-16"])
+def test_list_filters_before_limit(list_store, monkeypatch, capsys, as_json, since):
+ class Clock(datetime):
+ @classmethod
+ def now(cls, tz=None):
+ return cls(2026, 10, 23, tzinfo=UTC)
+
+ monkeypatch.setattr(cli, "datetime", Clock)
+ flags = ["--json"] if as_json else []
+ assert cli.main(["list", "--agents", "codex", "--since", since, "--limit", "2", *flags]) == 0
+ out = capsys.readouterr().out
+ ids = [r["sessionId"] for r in json.loads(out)] if as_json else [s.strip() for s in out.splitlines()[1::2]]
+ assert ids == ["imported", "updated"]
+
+
[email protected](("flags", "expected"), [
+ ([], ["other", "imported", "stale", "updated", "old-import", "undated"]),
+ (["--agents", "codex, claude-code", "--limit", "1"], ["other"]),
+ (["--agents", "cursor"], []),
+ (["--since", "2026-10-20T00:00:00Z"], ["other", "updated"]),
+])
+def test_list_filters_independently(list_store, capsys, flags, expected):
+ assert cli.main(["list", "--json", *flags]) == 0
+ assert [r["sessionId"] for r in json.loads(capsys.readouterr().out)] == expected
+
+
[email protected](("flags", "message"), [
+ (["--agents", "unknown"], "unknown agent"),
+ (["--since", "yesterday"], "can't read --since"),
+])
+def test_list_rejects_invalid_filters(list_store, flags, message):
+ with pytest.raises(SystemExit, match=message):
+ cli.main(["list", *flags])
+
+
[email protected]("filtered", [False, True])
+def test_list_empty_message(list_store, capsys, filtered):
+ flags = ["--agents", "cursor"] if filtered else []
+ if not filtered:
+ list_store.index.clear()
+ list_store.save_index()
+ assert cli.main(["list", *flags]) == 0
+ expected = "No sessions match these filters." if filtered else "No maps yet. Run `agentplay build`."
+ assert capsys.readouterr().out.strip() == expected