Replay your coding agent sessions as a map and a timeline
Python agent-observabilityai-agentsclaudeclaude-codecodexcoding-agentscursordeveloper-toolsdevtoolsgithub-copilotkirollmobservabilityopencodeprivacypythonsession-replaytypescriptvisualization
feat(cli): filter listed sessions by agent and time
gezerui8889f2d65c089ed
diff --git a/README.md b/README.mdindex 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.pyindex 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:# --------------------------------------------------------------------------- listdef 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 0if 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 0for 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.pyindex 831132e..4d13a81 100644--- a/python/tests/test_cli_output.py+++ b/python/tests/test_cli_output.py@@ -3,6 +3,7 @@from __future__ import annotationsimport io+import jsonimport loggingfrom collections import Counterfrom datetime import UTC, datetime@@ -165,3 +166,74 @@ def test_view_says_when_the_requested_port_is_busy(monkeypatch, capsys, requesteout, err = capsys.readouterr()assert (f"Port {requested} is busy; using {bound} instead." in err) is noticeassert 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