The short answer
AgentSight v1.0.31 scans four provider-owned roots: Claude Code under ~/.claude/projects, Codex under $CODEX_HOME/sessions or ~/.codex/sessions, Gemini CLI under~/.gemini/tmp, and Cursor under ~/.cursor/projects. It recognizes provider-specific transcript formats, orders candidates by update time, deduplicates the visible session list, and clamps the ordinary list path to at most 25 sessions.
Two providers also have read-only database paths that avoid treating every list operation as a full transcript parse. Codex can use state_5.sqlite as a thread index. Cursor can use its localstate.vscdb to enrich an already-discovered transcript with composer timestamps, model, workspace, and token counts. Those databases are optimizations and enrichment sources, not replacements for provider-owned transcript files.
What AgentSight scans before it parses anything
| Agent | Discovery root | Recognized transcript | Session-ID path |
|---|---|---|---|
| Claude Code | ~/.claude/projects | JSONL beneath .claude | The transcript file stem is the session ID. |
| Codex | $CODEX_HOME/sessions when CODEX_HOME is absolute; otherwise ~/.codex/sessions | JSONL beneath .codex; state_5.sqlite can provide the recent-thread index. | The scanner extracts session_meta.id from a bounded header; the SQLite path already supplies the thread ID. |
| Gemini CLI | ~/.gemini/tmp | JSON session files beneath .gemini | The bounded JSON header supplies sessionId. |
| Cursor | ~/.cursor/projects | JSONL under agent-transcripts, plus sibling subagent JSONL files | The parent transcript file stem is the composer/session ID; duplicate candidates are collapsed. |
Path ownership and format are part of classification. AgentSight does not recursively treat every JSON or JSONL file in the home directory as agent history. That reduces false positives, but it also means an upstream storage-layout change can make a real provider session temporarily undiscoverable until the parser is updated.
Discovery is an index first, transcript parsing second
The list path is intentionally bounded. The native analysis layer asks the session cache for recent candidates, optionally substitutes the Codex SQLite index, sorts by update time, truncates to limit.clamp(1, 25), removes duplicate display IDs, enriches Cursor rows, and only then applies optional PID or text filters.
Direct detail lookup follows a different path so the 25-row list cap does not make an older known session impossible to open. AgentSight keeps an ID-to-path candidate index. If the ID is missing or its path vanished, it rebuilds that index from discovered session files, refreshes only the matching candidate, parses it through the shared cache, verifies that the parsed session_id still matches, and then hydrates detail.
For Codex and Gemini, the ID index reads only the first 64 KiB when it needs the provider-native session ID. Claude and Cursor can use the file stem directly. This is a useful troubleshooting distinction: list discovery, ID resolution, and full transcript parsing are separate failure points.
Codex uses a read-only SQLite fast path
When state_5.sqlite is readable, AgentSight opens it with SQLite read-only flags and selects recent rows from threads ordered by updated_at_ms. The query reads the thread ID, rollout path, model, token total, preview, working directory, and created/updated timestamps. That is enough to construct a useful recent-session row without first parsing the whole rollout.
The implementation still consults the rollout for summary fields that are not reliably represented by the thread row. It reads at most the final 1 MiB, extracts the latest token usage and plan information, and caches that summary by path, file length, and modification time. The summary cache is bounded to 64 entries and is cleared before accepting a new path when already full.
If the Codex database is absent or cannot be opened, discovery falls back to cached transcript scanning rather than failing all native-session discovery. Likewise, CODEX_HOME is honored only when it resolves to an absolute path; otherwise AgentSight falls back to ~/.codex.
Cursor has two layers: transcript discovery and state-database enrichment
Cursor discovery starts from ~/.cursor/projects. A parent transcript's freshness includes the newest sibling subagents/*.jsonl modification time, so delegated work can keep the parent session recent. If more than one Cursor candidate has the same file stem, AgentSight prefers a candidate outside the special empty-window tree and otherwise keeps the newer candidate.
After discovery, AgentSight looks for Cursor's state.vscdb in the standard macOS, Linux, or Windows application-data locations and opens the database read-only. For the matching composer ID it can usecomposerHeaders for created/updated timestamps and cursorDiskKV composer data for the selected model and workspace path. If those records are missing, the transcript-derived row remains usable.
Token enrichment also comes from Cursor's local key-value records. AgentSight sums input and output tokens for the parent composer's bubbleId records, then rolls up the same counters for discovered subagent IDs. That detail matters for delegated Cursor runs: reading only the parent transcript or only the parent composer counters can under-report the session that delegated the work.
Hydrated detail is intentionally bounded
A matching transcript can still be very large, so AgentSight bounds the detail payload after hydration. v1.0.31 retains at most 1,000 prompts, 2,000 LLM responses, and 2,000 tool events. Prompt and response text each share a 2 MiB budget; tool command text gets 1 MiB. Per-tool process chains are capped at 16 entries, while path groups, paths, and domains are capped at 32 each.
The truncation logic keeps the newest events and spends text budgets from newest to oldest. That makes the returned detail a bounded recent representation, not proof that every byte of an arbitrarily large provider transcript was returned. Keep the provider-native artifact when an investigation requires the complete source.
Why a local session can be missing or look incomplete
| Symptom | Implementation-level check |
|---|---|
| An old session is not in the normal list. | List discovery is bounded to the requested limit and never more than 25 rows; callers can also supply a maximum-age window. |
| Codex sessions disappeared after moving its home. | Verify that CODEX_HOME is an absolute path and that its sessions tree or state_5.sqlite remains readable. |
| A transcript-shaped file is ignored. | Provider path ownership and expected extension matter; an arbitrary JSON/JSONL file is not admitted as native session state. |
| A Cursor session has no model/workspace/token enrichment. | Transcript discovery can succeed even when state.vscdb is absent, unreadable, or lacks the matching composer records. |
| A delegated Cursor run looks smaller than expected. | Check that the sibling subagent transcripts are still present; AgentSight discovers their IDs and rolls their bubble-token counts into the parent when state records exist. |
| A direct detail lookup returns no session. | The indexed path must still exist, the candidate must parse, and the parsed provider session ID must exactly match the requested ID. |
Start with the provider's native state and discovery root before assuming an eBPF or network problem. Local session discovery is a provider-state path; system capture is a separate sensor. The no-eBPF evidence guide explains when each boundary is useful.
Provider state is useful evidence, but it is not an independent system trace
Native state can be the strongest source for provider session IDs, prompts, model metadata, tool semantics, token fields, and plan information. It is not independent proof of every process, file, or network effect. A missing native row can mean a discovery/layout/parser boundary; a missing system row can mean a sampling, privilege, process-family, or runtime-coverage boundary. Neither absence should be promoted into a universal claim that an action never happened.
For the normalization step after discovery, read how AgentSight maps provider transcripts into one session model. For independent runtime evidence, see the eBPF agent monitoring boundary map.
Primary sources and research scope
- AgentSight v1.0.31 session parser: discovery roots, path classification, Cursor deduplication, and provider file formats
- AgentSight v1.0.31 native analysis source: Codex indexing, Cursor state enrichment, bounded ID lookup, caching, and hydration
- AgentSight v1.0.31 README: native-session workflows and current platform boundary
- AgentSight v1.0.31 usage guide: top, bind, report, and vis behavior
Research scope: AgentSight v1.0.31 at commit bb99b66f8f98, inspected on 22 September 2026. The session-discovery implementation itself is unchanged from the v1.0.30 snapshot this article previously cited; this refresh re-verifies that implementation against the current release and adds the previously undocumented Cursor state-database enrichment and delegated-token rollup path. Provider storage formats can change independently, so validate newer releases against current source.