Skip to content

Replay your coding agent sessions as a map and a timeline

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.py
index 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 scan
print(_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.py
index 8ad377a..2e3ed0b 100644
--- a/python/src/agentplay/pipeline.py
+++ b/python/src/agentplay/pipeline.py
@@ -16,6 +16,9 @@ from .store import Store
logger = logging.getLogger("agentplay.pipeline")
+# How often a long build writes the index mid-run (seconds).
+SAVE_EVERY_S = 2.0
+
@dataclass
class 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 = False
for i, c in enumerate(cands):
+ if pending and time.monotonic() - last_save >= SAVE_EVERY_S:
+ store.save_index()
+ last_save, pending = time.monotonic(), False
if 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 None
task_titles = discover.local_task_titles(c, source) if titles else None
store.put(doc, _row(doc, c, title, task_titles))
+ pending = True
report.built += 1
report.by_agent[c.agent] += 1
store.save_index()
diff --git a/python/src/agentplay/server.py b/python/src/agentplay/server.py
index 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 = 15
store: Store
static: 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 = None
lock = 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.py
index 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"]) == 0
out, err = capsys.readouterr()
assert (f"Port {requested} is busy; using {bound} instead." in err) is notice
diff --git a/python/tests/test_local_tool.py b/python/tests/test_local_tool.py
index 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"]) == 1
row = page["sessions"][0]
diff --git a/viewer/README.md b/viewer/README.md
index 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.tsx
index 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.ts
index a7c3693..3406917 100644
--- a/viewer/src/core/schema.ts
+++ b/viewer/src/core/schema.ts
@@ -24,6 +24,8 @@ export const sessionExplorerStatusSchema = z
available: 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.ts
index 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.ts
index 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.ts
index 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.tsx
index 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>
);
}