Replay your coding agent sessions as a map and a timeline
Python agent-observabilityai-agentsclaudeclaude-codecodexcoding-agentscursordeveloper-toolsdevtoolsgithub-copilotkirollmobservabilityopencodeprivacypythonsession-replaytypescriptvisualization
fix(viewer): show the background scan instead of an empty list on first run
depak_7467003403fb6
diff --git a/python/src/agentplay/cli.py b/python/src/agentplay/cli.pyindex 20880a1..341a485 100644--- a/python/src/agentplay/cli.py+++ b/python/src/agentplay/cli.py@@ -180,20 +180,23 @@ def cmd_build(args: argparse.Namespace, *, quiet: bool = False) -> pipeline.Buil# --------------------------------------------------------------------------- view-def _background_scan(args: argparse.Namespace) -> None:+def _background_scan(args: argparse.Namespace, scanning: threading.Event) -> None:"""Scan for new sessions beside a running viewer.Failures are reported and dropped: a bad transcript must not take the viewer- down with it, and everything already built stays servable.+ down with it, and everything already built stays servable. ``scanning`` is+ cleared either way, which is how the open viewer learns the scan is over."""try:rep = cmd_build(args, quiet=True)except Exception as exc: # noqa: BLE001 - the viewer outlives a failed scanprint(_dim(f"Scan failed: {type(exc).__name__}: {exc}"), file=sys.stderr, flush=True)return+ finally:+ scanning.clear()built = f"{rep.built} new" if rep.built else "nothing new"skipped = f", {rep.skipped} skipped{_skip_breakdown(rep)}" if rep.skipped else ""- print(_dim(f"Scan done: {built} of {rep.found} sessions{skipped} in {rep.seconds}s. Reload to see them."), flush=True)+ print(_dim(f"Scan done: {built} of {rep.found} sessions{skipped} in {rep.seconds}s."), flush=True)def cmd_view(args: argparse.Namespace) -> int:@@ -203,7 +206,12 @@ def cmd_view(args: argparse.Namespace) -> int:# (decoding database-backed agents such as Cursor dominates it), and# everything already built is servable immediately; the index is re-read# as new maps land.- httpd = serve(args.port)+ scanning = threading.Event()+ if not args.no_build:+ # Set before the server answers anything, so the viewer's first status+ # call already says a scan is under way.+ scanning.set()+ httpd = serve(args.port, scanning=scanning)port = httpd.server_address[1]if args.port and port != args.port:print(f"Port {args.port} is busy; using {port} instead.", file=sys.stderr, flush=True)@@ -216,7 +224,7 @@ def cmd_view(args: argparse.Namespace) -> int:print(f"Viewer → {_b(url)} {_dim('(Ctrl+C to stop)')}", flush=True)if not args.no_build:print(_dim("Scanning for new sessions in the background…"), flush=True)- threading.Thread(target=_background_scan, args=(args,), daemon=True).start()+ threading.Thread(target=_background_scan, args=(args, scanning), daemon=True).start()if not args.no_open:threading.Timer(0.3, lambda: webbrowser.open(url)).start()try:diff --git a/python/src/agentplay/pipeline.py b/python/src/agentplay/pipeline.pyindex 8ad377a..2e3ed0b 100644--- a/python/src/agentplay/pipeline.py+++ b/python/src/agentplay/pipeline.py@@ -16,6 +16,9 @@ from .store import Storelogger = logging.getLogger("agentplay.pipeline")+# How often a long build writes the index mid-run (seconds).+SAVE_EVERY_S = 2.0+@dataclassclass BuildReport:@@ -177,7 +180,14 @@ def build_all(for reason, n in walk["skipped"].items():if reason not in ("different_agent", "subagent_component"):report.skip(reason, n)+ # Saved as it goes, not only at the end: `view` serves while this runs, and a+ # first scan can take minutes, so the open viewer fills in as maps land.+ last_save = time.monotonic()+ pending = Falsefor i, c in enumerate(cands):+ if pending and time.monotonic() - last_save >= SAVE_EVERY_S:+ store.save_index()+ last_save, pending = time.monotonic(), Falseif progress:progress(i, len(cands), c.session_id)if not rebuild and store.is_fresh(c.session_id, c.mtime, built_with=__version__, path_mode=effective_mode):@@ -202,6 +212,7 @@ def build_all(title = discover.local_title(c, source) if titles else Nonetask_titles = discover.local_task_titles(c, source) if titles else Nonestore.put(doc, _row(doc, c, title, task_titles))+ pending = Truereport.built += 1report.by_agent[c.agent] += 1store.save_index()diff --git a/python/src/agentplay/server.py b/python/src/agentplay/server.pyindex 454760c..9aa8b3a 100644--- a/python/src/agentplay/server.py+++ b/python/src/agentplay/server.py@@ -3,7 +3,7 @@Binds to 127.0.0.1 only. Serves the static viewer from the package's``viewer/`` directory and these endpoints over the local store:-``GET /api/status`` ``{available, mapCount, latestSessionDate}``+``GET /api/status`` ``{available, mapCount, latestSessionDate, scanning}````GET /api/sessions`` paged session rows (``from``, ``to``, ``search``, ``pageSize``, ``cursor``)``GET /api/map`` one entry per ``session_id`` param, each with a ``url````GET /api/map-doc?id=...`` the map document itself@@ -189,6 +189,9 @@ class _Handler(BaseHTTPRequestHandler):timeout = 15store: Storestatic: Path | None+ # Set while `agentplay view` is scanning in the background, so the viewer+ # can tell "no sessions yet" from "no sessions".+ scanning: threading.Event | None = Nonelock = threading.Lock()def log_message(self, fmt: str, *args: Any) -> None: # quiet by default@@ -374,7 +377,9 @@ class _Handler(BaseHTTPRequestHandler):def _status(self) -> None:rows = self._rows()latest = max((r.get("sessionDate") or "" for r in rows), default="") or None- self._json({"success": True, "available": bool(rows), "mapCount": len(rows), "latestSessionDate": latest})+ scanning = bool(self.scanning and self.scanning.is_set())+ self._json({"success": True, "available": bool(rows), "mapCount": len(rows), "latestSessionDate": latest,+ "scanning": scanning})def _sessions(self, q: dict[str, list[str]]) -> None:rows = self._rows()@@ -501,9 +506,18 @@ class _Handler(BaseHTTPRequestHandler):self._json({"success": True, "message": message, "command": command})-def serve(port: int = 7317, *, store: Store | None = None, host: str = "127.0.0.1") -> ThreadingHTTPServer:- """Create (but do not start) the local server. Call ``serve_forever()`` on the result."""- handler = type("Handler", (_Handler,), {"store": store or Store(), "static": viewer_root()})+def serve(+ port: int = 7317,+ *,+ store: Store | None = None,+ host: str = "127.0.0.1",+ scanning: threading.Event | None = None,+) -> ThreadingHTTPServer:+ """Create (but do not start) the local server. Call ``serve_forever()`` on the result.++ ``scanning``: set while a background scan runs; ``/api/status`` reports it.+ """+ handler = type("Handler", (_Handler,), {"store": store or Store(), "static": viewer_root(), "scanning": scanning})try:return _Server((host, port), handler)except OSError:diff --git a/python/tests/test_cli_output.py b/python/tests/test_cli_output.pyindex c272971..831132e 100644--- a/python/tests/test_cli_output.py+++ b/python/tests/test_cli_output.py@@ -160,7 +160,7 @@ class _FakeServer:def test_view_says_when_the_requested_port_is_busy(monkeypatch, capsys, requested, bound, notice) -> None:from agentplay import server- monkeypatch.setattr(server, "serve", lambda _port: _FakeServer(bound))+ monkeypatch.setattr(server, "serve", lambda _port, **_kw: _FakeServer(bound))assert cli.main(["view", "--port", str(requested), "--no-open", "--no-build"]) == 0out, err = capsys.readouterr()assert (f"Port {requested} is busy; using {bound} instead." in err) is noticediff --git a/python/tests/test_local_tool.py b/python/tests/test_local_tool.pyindex d8185d3..a45a62f 100644--- a/python/tests/test_local_tool.py+++ b/python/tests/test_local_tool.py@@ -478,6 +478,49 @@ def test_server_picks_up_sessions_built_while_it_runs(env):httpd.server_close()+def test_status_reports_a_background_scan(env):+ """The viewer tells "no sessions yet" from "no sessions" by this flag."""+ scanning = threading.Event()+ scanning.set()+ httpd = serve(0, store=Store(env["sm"]), scanning=scanning)+ threading.Thread(target=httpd.serve_forever, daemon=True).start()+ base = f"http://127.0.0.1:{httpd.server_address[1]}"++ def status() -> dict[str, Any]:+ with urllib.request.urlopen(f"{base}/api/status") as r:+ return json.loads(r.read())++ try:+ assert status()["scanning"] is True and status()["mapCount"] == 0+ scanning.clear()+ assert status()["scanning"] is False+ finally:+ httpd.shutdown()+ httpd.server_close()+++def test_long_build_saves_the_index_as_it_goes(env, monkeypatch):+ """A first scan can take minutes; the viewer should not sit on an empty list+ until it ends, so the index is written mid-run too."""+ for n in range(3):+ _write_claude_session(env["home"], f"9999999{n}-0000-0000-0000-00000000000{n}", env["repo"])+ monkeypatch.setattr(pipeline, "SAVE_EVERY_S", 0.0)+ saves = 0+ real = Store.save_index++ def counting(self: Store) -> None:+ nonlocal saves+ saves += 1+ real(self)++ monkeypatch.setattr(Store, "save_index", counting)+ rep = pipeline.build_all(agents={"claude-code"}, store=Store(env["sm"]))+ assert rep.built == 3+ # One after each of the first two maps, plus the final save.+ assert saves == 3+ assert len(Store(env["sm"]).index) == 3++def test_reload_if_changed_is_opt_in_because_it_discards_pending_writes(env):"""Why the reload is an explicit call and not a check inside `index`.@@ -518,7 +561,8 @@ def test_server_endpoints(env):try:status = get("/api/status")- assert status == {"success": True, "available": True, "mapCount": 1, "latestSessionDate": "2026-09-10"}+ assert status == {"success": True, "available": True, "mapCount": 1, "latestSessionDate": "2026-09-10",+ "scanning": False}page = get("/api/sessions?pageSize=10")assert page["hasMore"] is False and len(page["sessions"]) == 1row = page["sessions"][0]diff --git a/viewer/README.md b/viewer/README.mdindex 5762f66..fc695b1 100644--- a/viewer/README.md+++ b/viewer/README.md@@ -62,7 +62,9 @@ at a server on another origin.All answers are camelCase JSON, validated by the zod schemas in`src/core/schema.ts`:-- `GET /api/status` -> `{success, available, mapCount, latestSessionDate}`+- `GET /api/status` -> `{success, available, mapCount, latestSessionDate,+ scanning}`; while `scanning` is true the viewer polls it and refreshes the+ session list as maps land- `GET /api/sessions?from=&to=&search=&pageSize=50&cursor=` ->`{success, sessions: [row], nextCursor, hasMore}`- `GET /api/map?session_id=A&session_id=B` -> `{success, expiresIn, maps:diff --git a/viewer/src/App.tsx b/viewer/src/App.tsxindex e5c4fd0..4bf3784 100644--- a/viewer/src/App.tsx+++ b/viewer/src/App.tsx@@ -230,6 +230,7 @@ function AppBar({<Badge variant="keyline">{source.label}{count != null ? ` · ${count} ${count === 1 ? 'map' : 'maps'}` : ''}+ {status.data?.scanning ? ' · scanning…' : ''}</Badge>) : null}{onBack ? (diff --git a/viewer/src/core/schema.ts b/viewer/src/core/schema.tsindex a7c3693..3406917 100644--- a/viewer/src/core/schema.ts+++ b/viewer/src/core/schema.ts@@ -24,6 +24,8 @@ export const sessionExplorerStatusSchema = zavailable: z.boolean().catch(false).default(false),mapCount: z.number().catch(0).default(0),latestSessionDate: z.string().nullable().catch(null).default(null),+ /** the local server is still scanning for sessions, so more may land */+ scanning: z.boolean().catch(false).default(false),}).passthrough();export type SessionExplorerStatus = z.infer<typeof sessionExplorerStatusSchema>;diff --git a/viewer/src/data/demoSource.ts b/viewer/src/data/demoSource.tsindex e7c3c81..cb899a0 100644--- a/viewer/src/data/demoSource.ts+++ b/viewer/src/data/demoSource.ts@@ -40,7 +40,7 @@ export function demoSource(root = 'demo/'): SessionMapSource {async status() {const rows = await load();const latest = rows.map((r) => r.sessionDate ?? '').sort().pop() || null;- return { success: true, available: rows.length > 0, mapCount: rows.length, latestSessionDate: latest };+ return { success: true, available: rows.length > 0, mapCount: rows.length, latestSessionDate: latest, scanning: false };},async sessions(params) {return listRows(await load(), params);diff --git a/viewer/src/data/fileSource.ts b/viewer/src/data/fileSource.tsindex 67bf758..f46a7fe 100644--- a/viewer/src/data/fileSource.ts+++ b/viewer/src/data/fileSource.ts@@ -63,7 +63,7 @@ export function fileSource(): FileSource {async status() {const rows = [...docs.values()].map((d) => d.row);const latest = rows.map((r) => r.sessionDate ?? '').sort().pop() || null;- return { success: true, available: rows.length > 0, mapCount: rows.length, latestSessionDate: latest };+ return { success: true, available: rows.length > 0, mapCount: rows.length, latestSessionDate: latest, scanning: false };},async sessions(params) {return listRows([...docs.values()].map((d) => d.row), params);diff --git a/viewer/src/data/hooks.ts b/viewer/src/data/hooks.tsindex bad0687..b3752d9 100644--- a/viewer/src/data/hooks.ts+++ b/viewer/src/data/hooks.ts@@ -1,4 +1,4 @@-import { useCallback, useEffect } from 'react';+import { useCallback, useEffect, useRef } from 'react';import {keepPreviousData,useInfiniteQuery,@@ -17,8 +17,12 @@ import { useSessionMapSource } from './SourceContext';export const sessionExplorerStatusKey = (sourceId: string) =>['sessionExplorerStatus', sourceId] as const;+/** How often to re-ask while the server is still scanning. */+const SCANNING_POLL_MS = 2000;+/** Whether the injected source has any maps. Fails closed: any error reads- * as "not available" in the caller. */+ * as "not available" in the caller. Polls while the server reports a scan+ * in progress, and stops once it is done. */export function useSessionExplorerStatus() {const source = useSessionMapSource();return useQuery({@@ -26,6 +30,7 @@ export function useSessionExplorerStatus() {queryFn: () => source.status(),staleTime: 3 * 60 * 1000,retry: false,+ refetchInterval: (q) => (q.state.data?.scanning ? SCANNING_POLL_MS : false),});}@@ -37,6 +42,23 @@ export function useSessionExplorerSessions(enabled = true) {const source = useSessionMapSource();+ const queryClient = useQueryClient();+ // A background scan adds sessions after the list first loaded: refetch it+ // whenever the count moves or the scan ends. The first answer is only+ // recorded, so a cold load does not fetch the list twice.+ const status = useSessionExplorerStatus();+ const stamp = status.data ? `${status.data.mapCount}:${status.data.scanning}` : null;+ const lastStamp = useRef<string | null>(null);+ useEffect(() => {+ if (stamp == null) return;+ const prev = lastStamp.current;+ lastStamp.current = stamp;+ if (prev != null && prev !== stamp) {+ void queryClient.invalidateQueries({+ queryKey: ['sessionExplorerSessions', source.id],+ });+ }+ }, [stamp, queryClient, source.id]);return useInfiniteQuery({queryKey: ['sessionExplorerSessions',diff --git a/viewer/src/explorer/SessionExplorer.tsx b/viewer/src/explorer/SessionExplorer.tsxindex 163ebef..a6f5e45 100644--- a/viewer/src/explorer/SessionExplorer.tsx+++ b/viewer/src/explorer/SessionExplorer.tsx@@ -36,6 +36,7 @@ import { useDebounce } from '@/hooks/useDebounce';import {useSessionExplorerMap,useSessionExplorerSessions,+ useSessionExplorerStatus,} from '@/data/hooks';import { WINDOW_OPTIONS, type WindowKey } from '@/core/windowOptions';import { ExplorerToolbar } from './ExplorerToolbar';@@ -217,6 +218,7 @@ export function SessionExplorer({}: Props) {const data = useExplorerSessions(windowKey);const { list, sessions, selectedId } = data;+ const scanning = !!useSessionExplorerStatus().data?.scanning;const [, setScopeParams] = useQueryStates(SCOPE_PARAMS);// One sidebar: the list until a session is picked (or one is linked), then// only that session; "All sessions" flips back without touching the URL.@@ -262,12 +264,22 @@ export function SessionExplorer({return (<div className="flex flex-col gap-3">{windowSelect ? <div className="w-48">{windowSelect}</div> : null}- <EmptyState- icon={<MapTrifold size={24} weight="duotone" />}- title="No session maps yet"- description="Session maps appear here once a coding-agent session has been indexed. Try a longer window if you expected one."- action={emptyAction}- />+ {scanning ? (+ // The first scan is still running: "none yet" would be a false+ // answer. The list fills in by itself as maps land.+ <EmptyState+ icon={<MapTrifold size={24} weight="duotone" />}+ title="Scanning your sessions…"+ description="agentplay is building maps from your coding-agent sessions. They appear here as they are ready."+ />+ ) : (+ <EmptyState+ icon={<MapTrifold size={24} weight="duotone" />}+ title="No session maps yet"+ description="Session maps appear here once a coding-agent session has been indexed. Try a longer window if you expected one."+ action={emptyAction}+ />+ )}</div>);}