Usage Guide

AgentsView serves a full-featured web application for browsing, searching, and analyzing your AI agent sessions. This page walks through every part of the interface.

Dashboard¶

If your archive is empty, AgentsView shows No sessions yet and lists the folders it reads for sessions. Choose folders opens Settings > Session Providers, where you can configure those sources.

With sessions in your archive and no session selected, you see the analytics dashboard. It provides a high-level overview of your agent activity across all projects, including when filters hide every session in the sidebar.

The dashboard header includes:

• Project filter — typeahead to scope everything to a single project. Type to filter by name; each entry shows its session count. Navigate with arrow keys, select with Enter, and close with Escape.
• Search bar — opens the command palette (Cmd+K)
• Sync button — triggers a manual sync of session files
• Theme toggle — switch between light and dark mode
• Import button — opens the Chat Import dialog for importing Claude.ai or ChatGPT conversations
• Shortcuts button (?) — shows all keyboard shortcuts

The status bar at the bottom shows session count, message count, project count, last sync time, and the build version.

On the normal local agentsview serve runtime, the session lists in the sidebar update automatically from a global SSE event stream (debounced during busy syncs). The dashboard and Activity page do not refetch their charts on every sync event — each pairs a manual refresh button with a relative "Updated…" timestamp, and the Analytics dashboard also refreshes periodically on its own. Use refresh or change the date range for an immediate update.

Usage refreshes after session data changes and on its five-minute timer, at most once a minute while visible. It pauses while hidden and catches up when you return.

For range-based concurrency and agent-minutes reporting, use the top-level Activity page.

Summary Cards¶

Six cards at the top of the dashboard show key metrics for the selected date range:

Git and Pull-Request Totals¶

The Outcomes panel shows repositories, commits, lines added and removed, and files changed for the selected dates. It reads Git history from the repositories associated with matching sessions. Repositories shared by clones or worktrees count once, and each commit counts once across their branches.

Configure GitHub in Settings, then choose Include pull requests to add opened and merged totals. This requests GitHub data for each repository and can take minutes. A Not counted list identifies repository operations that failed, so partial totals are visible.

The panel reports when the backend or selected filters cannot provide outcome totals. Clear machine, model, termination, minimum-message, recent-activity, and time-of-day filters to use it. The CLI exposes the same metrics through agentsview report stats.

Date Range Picker¶

Quick presets for 7 days, 30 days, 90 days, 1 year, and All, plus custom start/end date inputs. The All preset shows every session regardless of age. All charts update when the range changes. The same range picker is used on the dashboard, the Usage page, and the Activity page so presets and behavior stay consistent across panels.

Preset ranges are rolling by default: a page left open across midnight rolls the window forward at the next refresh tick, sync event, or manual refresh, instead of staying anchored to the day it loaded. Manually editing either date input pins the range. On Usage and Activity, explicit date parameters remain authoritative. A bare Usage URL returns to its rolling 30-day default; a bare Activity URL returns to its current-day calendar default unless an enabled shared range supplies another selection. The All preset always pins to (earliest_session, today).

Bare pages use independent defaults: the Sessions dashboard opens to a rolling 1-year range, Usage opens to a rolling 30-day range, and Activity opens to the current day. Cross-page linking is disabled by default because applying a broad range automatically can make some pages run substantially more expensive queries.

To carry selections among Sessions, Usage, Activity, Trends, and Quality, enable Settings > Date ranges > Link date ranges across pages. An explicit dated URL always controls the target page. With linking enabled, that selection can then carry to date-aware pages opened later at their bare URLs.

Model Filter¶

The dashboard toolbar includes a Model dropdown that scopes every panel to one or more AI models. By default the button reads Model: All and nothing is filtered.

Open the dropdown for a searchable list of the models found in your sessions, then click models to include them. The button then shows the chosen model — for example Model: gpt-4o — or Model: 3 selected once several are active. Click the All models row at the top of the list to clear the filter and return to every model. Selected models also appear as removable chips beneath the toolbar.

While a model filter is active, every dashboard panel reflects only the selected model(s): the summary cards, activity chart, heatmap, hour-of-week grid, projects, session shape, velocity, tools, skills, top sessions, and the Session Health rollup.

Model filtering is message-grain, unlike the session-grain project and agent filters, because a single session can switch models across turns. A session is included when it has at least one message from a selected model, and most panels count only the matching messages. The user turn paired with a matching assistant turn is kept alongside it — even though a user message carries no model of its own — so prompts and their responses stay aligned in the counts and in the top-session evidence.

Session Health is the exception. It is scoped to whole sessions that used the selected model, but its health scores, outcomes, tool-failure rates, and compaction counts stay whole-session aggregates — they are not recomputed from only that model's messages.

Activity Heatmap¶

A GitHub-style contribution graph showing daily activity. Toggle between message count and session count.

Click-to-Filter¶

Click any heatmap cell to filter all charts and the session list to that single day. The selected cell gets a highlighted border, and an active filter chip appears in the toolbar. Click the same cell again (or dismiss the filter chip) to deselect.

Hour of Week Heatmap¶

A 7x24 grid showing when you use agents most. Rows are days of the week, columns are hours. Color intensity represents message volume.

Activity Timeline¶

Compare message or session counts over time. Switch between Day, Week, and Month to change how the chart groups activity.

Message bars separate User, Assistant, and Other entries. Other includes system entries and tool results. Choose Absolute to compare counts or Percent to compare each role's share of message volume. Session counts remain a separate metric.

Top Sessions¶

A ranked list of your longest sessions by message count or duration. Click any session to jump directly to it in the session viewer.

Project Breakdown¶

Bar chart of all projects sorted by session or message count. Shows average and median messages per session for each project. Click any project bar to filter the dashboard and session list to that project.

Session Shape Distribution¶

Three histograms showing the distribution of:

1. Session length — number of messages per session
2. Session duration — time in minutes
3. Session autonomy — ratio of tool calls to conversation turns

Tool Usage¶

Total tool call count with breakdowns by category (Read, Edit, Write, Bash, Search, Web, Task) and by agent. Includes a trend chart showing tool usage over time. Each tool also shows empty, repeat and recovery rates. Click a nonzero rate to list the sessions behind it, with the number of matching calls in each. Each link opens the session at the message that holds the first matching call.

• Empty rate divides empty results by calls with a known outcome.
• Repeat rate divides calls that repeat the previous call's tool and input, exactly or after normalizing the JSON, by analyzed calls. The previous call's outcome does not matter, and calls in the same message do not count. A sequence's first call can repeat a previous successful call.
• Recovery rate divides recovered sequences by recovered plus abandoned sequences. A sequence starts with an empty result or an error. It recovers when a call in a later message returns content. The tool that started the sequence owns it. Sequences still open, or with an unknown ending, stay out of the denominator.

A rate with no denominator shows Unavailable. Rates follow the same filters as the rest of the Analytics page and count individual calls, so a date or model filter selects the calls made in that window or by that model.

The Analyzed column shows analyzed calls out of all calls. After an upgrade, AgentsView recomputes older sessions in the background. Until a session's recompute finishes, its calls count as not analyzed. Archives that store no tool results never analyze calls. PostgreSQL, DuckDB, and ClickHouse mirrors receive the results through their normal pushes.

For a model's assessment of one session, use Analyze tool effectiveness.

Top Skills¶

The Top Skills panel ranks skill-backed tool calls by call count, session count, recency, agent mix, and project mix. The adjacent Skill Usage Over Time chart plots the leading skills, folds the long tail into Other, and lets you switch between day, week, and month buckets or hide individual series. Both views follow the active Analytics date and session filters.

Skill analytics is populated from normalized skill_name metadata on tool calls and from inferred skill names when Codex or Cursor reads a SKILL.md file through a read-like tool call. It appears when your local transcripts include either explicit skill metadata or enough SKILL.md reads for AgentsView to infer the skill name.

Velocity Metrics¶

Performance metrics including:

• Turn cycle time (p50, p90)
• First response time (p50, p90)
• Messages, characters, and tool calls per active minute
• Breakdown by agent and by session complexity

Agent Comparison¶

Side-by-side metrics across agents: session count, total messages, average response time, tool usage patterns, and concentration metrics.

Session Health¶

The 0.23.0 dashboard adds a Session Health section that rolls up the new session-intelligence signals. It shows:

• average health score and derived grade
• headline counts for the completed and errored outcomes (abandoned and unknown sessions are not counted here, but are visible in the dashboard's outcome-distribution chart alongside them)
• tool-failure rate and sessions with failures
• compaction counts, including mid-task compactions
• score trend over time
• by-agent and by-project score tables

See Session Intelligence for the full four-outcome model that both this section and agentsview report stats derive from.

CSV Export¶

Click Export CSV in the dashboard toolbar to download all analytics data as a CSV file. Includes summary, activity, projects, tools, and velocity sections.

Generated Insights¶

AgentsView can generate model-written reports over an explicit session scope using Claude, Codex, Copilot, Gemini, or Kiro. Open Recall → Generated insights to choose the date range, project, session agent, automated-session scope, template, generator, and optional focus.

See Recall for generation, archive, and privacy details.

Trends¶

Open More → Trends in the header navigation for ad-hoc term-frequency line charts over your session history. Type one term per line into the textarea, hit Refresh, and AgentsView counts how often each term appears in user and assistant message content over the selected window.

Use Trends to track topics or technologies as your work shifts over time — for example, plotting rust, typescript, and python to see which language you've been spending the most time in this quarter, or watching whether mentions of a problem keyword like flaky or timeout are trending up or down.

The toolbar controls the window and resolution:

• From / To — date inputs at the top of the page; defaults cover the last year.
• Granularity — day, week, or month. Pick coarser buckets for longer windows.
• Normalize by number of messages — toggle to chart per-term rate instead of raw counts, so a busy week doesn't drown out a quiet one.

Each line in the Terms textarea is a separate term, capped at 12 terms per chart. Within a line, pipe-separated variants fold into a single series. AgentsView also adds a simple plural form (just appending s) for each variant, and for single-word variants ending in c it expands the silent-e stem (slic matches slice, slices, sliced, slicing) — beyond those two cases, spell out other forms explicitly as pipe variants:

rust
type|types|typing
docker|kubernetes|k8s

Matching is case-insensitive. Single-word matchers honor word boundaries — cat won't match catalog. Multi-word matchers match as substrings. Each line accepts up to 8 variants.

The chart panel uses one color per term. Hover a line to highlight that term's series and draw point markers at each bucket; for exact per-bucket counts, switch granularities or read off the y-axis. The companion table below the chart lists each term's color swatch, expanded variants, and total — Count in raw mode or Per 1k messages in normalized mode.

Page state lives in the URL — from, to, granularity, normalized, and repeated term= parameters — so any view is shareable and bookmarkable.

The same data is available through the GET /api/v1/trends/terms endpoint for scripting, and works under both local agentsview serve and shared pg serve deployments.

Session Browser¶

The left sidebar lists all sessions with virtual scrolling for smooth performance even with thousands of sessions. On desktop, drag the resize handle between the sidebar and the content pane to adjust the sidebar width. The width is constrained between 220px and 520px, always leaving at least 480px for the content area. Your preferred width is saved in localStorage and restored on next visit.

As of 0.30.0, the sidebar loads from a skinny session-index endpoint and hydrates the visible rows on demand, so large refresh storms (e.g. after a bulk import or resync) no longer freeze the list while the full payloads arrive.

Each session item shows:

• Status indicator — small dot on the left whose color and animation reflect both how recently the session was active and whether it ended cleanly. See Session status indicator for the full state set.
• Session name — the name you gave the session in AgentsView, otherwise the agent's own title for it, otherwise the first message. As of 0.33.0, labels are no longer hard-truncated at 50 characters — the full label is clipped responsively to the sidebar width instead.
• Agent-provided session names — AgentsView shows the title each agent keeps for a session. When an agent records both a name you chose (for example with /rename) and a title it generated, your name wins. Agents with titles: Claude Code (/rename names and generated titles), Codex (session_index.jsonl thread names), Qwen Code, Copilot CLI (workspace.yaml names), Gemini CLI (generated summaries), Kimi CLI, OpenClaw, OpenCode, Kilo, MiMo Code, Amp, VS Code Copilot, Positron, Windsurf, Kiro, Claude.ai and ChatGPT conversation names, Forge, Hermes, Piebald, Cortex Code, WorkBuddy, and Command Code. The first message stays the first thing you typed; a title stands in for it only when a session has no user message. Manual in-app renames always take precedence and are never overwritten by an agent-provided name. As of 0.34.0, Codex titles renamed by the agent are imported from session_index.jsonl for both current and archived sessions. Qwen Code, Gemini CLI, Kimi CLI, and OpenClaw titles, current Claude Code /rename names, and keeping titles out of the first message are included in 0.45.0.
• Model name — the AI model used for the session, shown when available (including Codex session models).
• Star button — click the star icon or press s to star a session. Starred sessions persist in the SQLite database so they survive server restarts.
• Agent tag — agent name on the right side, tinted with the agent's accent color.
• Machine label — when using PostgreSQL sync, sessions from other machines show a machine name tag. Only visible in shared multi-host deployments.
• Project name — abbreviated, right-aligned
• Relative time — "2h ago", "Mon", "Dec 1"
• User prompt count — number of user messages in the session

Antigravity sessions show the conversation title Antigravity saves in conversation_summaries.db. Renames appear shortly after that file changes, or on the next agentsview source sync. Names set in AgentsView still win.

Qoder's database title lookup applies to ~/.qoder/projects and ~/.qoder-cn/projects. The Qoder app stores titles in main.sqlite under its data directory: com.qoder.app.stable (or com.qodercn.app.stable for Qoder CN) inside ~/Library/Application Support on macOS, $XDG_CONFIG_HOME or ~/.config on Linux, and %APPDATA% on Windows. If you moved the app's data directory, AgentsView does not find it. Names take precedence in this order:

1. A name set in AgentsView.
2. A non-blank database title.
3. A file-side name, with a sidecar title ahead of an in-chat rename.

Renames appear at the next sync pass: a watched change in any agent root, manual agentsview source sync, or startup. For these two roots, blank database titles or read errors preserve the archived name. A missing database, schema, or session row uses non-empty file-side names; an empty file-side name preserves the archived title. Other Qoder roots use file-side names, including clearing the archived title when empty.

When a session has a native resume target, the sidebar also exposes a direct native session link so supported agents can reopen their own session instead of only navigating inside AgentsView.

Session Status Indicator¶

As of 0.27.0, the small dot at the left edge of each session row encodes how recently the session was written to and how it last ended. The same indicator appears in the dashboard's Top Sessions list. Hover the dot for a tooltip explaining the current state.

The "flagged" tier (Stale and Unclean) is meant to surface sessions that look like an agent crashed mid tool call or had its session file truncated, so they're easy to pick out from sessions that simply haven't been touched in a while.

Termination classification currently runs for Claude Code and Codex sessions — those parsers read the per-message stop_reason (Claude) or task lifecycle events (Codex). Other agents render as plain time-based states (Working / Idle / Quiet) without the flagged tier.

When a parent session has subagents or a continuation chain, the dot reflects the freshest activity across the group: a parent in tool_call_pending whose subagent is currently writing rolls up to Working green. The parent's parser status still wins for the Waiting state — a fork running in parallel doesn't change that the parent has said "your turn".

Group by Agent¶

Click the group-by-agent toggle in the sidebar header to organize sessions into collapsible sections by agent type. Each agent group shows a color-coded dot, agent name, and session count. Click an agent header to expand or collapse its section. Groups start collapsed when first enabled.

Sub-Agent Tree¶

When a session spawns sub-agents or teams, the sidebar organizes them in a collapsible tree view. Parent sessions show a disclosure triangle; click to expand and see child agents nested underneath. This makes complex multi-agent workflows easier to navigate without leaving the session list.

Forks and Subagent Sessions¶

AgentsView automatically detects conversation forks in Claude Code sessions — for example, when you use "retry from here" to branch a conversation. Large forks (more than 3 user turns) appear as separate session entries grouped with their parent. Small retries fold into the main session.

Subagent sessions spawned by the Task tool are organized under their parent in the sidebar's sub-agent tree and are also viewable inline through the parent session's tool blocks (see Subagent Linking below). Claude companion session layouts are also linked when the parent can be inferred from the companion directory structure, including externalized tool result content stored beside the transcript.

Session Filters¶

Click the filter icon next to the session count to open a dropdown with several filter categories that can be combined:

Label and pull-request filters can find child and automated sessions. The sidebar shows the containing tree; an explicit single-turn exclusion still applies. Use launcher links to attach independently launched workers to their manager and roll up their costs.

• Starred — toggle to show only starred sessions
• Recently Active — toggle to show only sessions updated within the last 24 hours
• Agent — searchable multi-select of supported agents. Click an agent to toggle its selection; multiple agents can be active at once.
• Machine — searchable multi-select of machine labels. Surfaces in shared PostgreSQL sync deployments when more than five machines have pushed sessions.
• Status — three-pill multi-select of the status recency tiers (Active, Stale, Unclean), tinted to match the indicator colors. The underlying ?termination= URL parameter and API also accept the parser-side values clean and awaiting_user, but those aren't exposed as sidebar pills.
• Labels — enter an exact label such as ticket=example and press Enter. Add several labels to require all of them. Create labels through the CLI or API.
• Pull request — enter owner/repo#123 and press Enter to find sessions linked to that pull request by Claude Code.
• Min Prompts — filter to sessions with at least 2, 3, 5, or 10 user messages
• Include single-turn — toggle to include sessions with one or fewer user messages (excluded by default to reduce noise)
• Include automated — toggle to include sessions classified as automation (roborev runs, title generation, AgentsView's own internal prompts, and any patterns you've added to [automated] prefixes)
• Hide unknown — toggle to hide sessions whose project could not be determined

When any filter is active, a green dot appears on the filter button. Click Clear filters at the bottom of the dropdown to reset all filters at once.

As of 0.27.0, the sidebar filter store is shared with the analytics dashboard and the Usage page: agent, machine, project, min user-message threshold, hide-single-turn, and include-automated selections applied in the sidebar carry across to the dashboard panels and the Usage page header, which mounts the same filter widget. The Status filter is sidebar- and dashboard-only — the Usage page does not currently filter by termination status. Filter state is also persisted to localStorage and serialized into the URL.

Direct Session Links¶

Click Copy link to session in the detail header to copy a shareable URL. Clicking the Session ID copies only the ID. Session links give the provider and native ID separate path segments, for example:

/sessions/codex/550e8400-e29b-41d4-a716-446655440000

Older links with an encoded provider prefix still open. IDs without a provider prefix use a single segment after /sessions/.

Session URLs work as bookmarks and can be shared with teammates when using PostgreSQL sync for shared deployments.

A link from another tool that carries the agent's bare session UUID (Pi, OMP, Codex) opens the matching session. If the ID is ambiguous, use the full ID with its provider prefix.

Open a session by ID¶

Press Cmd+G on macOS or Ctrl+G elsewhere. Paste a complete session ID or UUID, then press Enter. This opens the session without changing the sidebar filters. If the UUID matches more than one session, use its full ID with the provider prefix, such as codex:550e8400-e29b-41d4-a716-446655440000.

URL Filters¶

URL parameters are supported for direct linking:

/sessions?project=myapp&agent=claude&date_from=2025-01-01

Available URL filters:

Unknown or ambiguous machine selectors, including stale saved filters, return HTTP 400 with known choices. The full selector stays selected until you edit or clear it.

A URL with one machine's display name, such as ?machine=Workstation, switches to that machine's ID after the server resolves it, so the picker shows it checked. Unknown or ambiguous names show an error instead of earlier results.

Navigation¶

Use ] and [ to move between sessions in the list. The selected session is highlighted with a left border accent.

Message Viewer¶

Selecting a session opens the message viewer in the main content area. Messages display in a scrollable list with virtual rendering for large sessions.

The session detail header shows the session name, agent, project, a health grade badge, and a copyable Session ID. Click the ID to copy it to the clipboard for sharing or lookup. Click the grade badge to toggle the signal panel.

The model badge shows the model used most often in assistant messages. For Claude Code and Codex, it also shows recorded reasoning effort, such as high, when that value is the most common effort for the displayed model. Effort is a model setting, not a measured token count. Upgrading resyncs existing sessions to populate it when the source files remain available.

If a parser skipped malformed source lines while still recovering the session, the header shows a malformed-lines badge with the persisted count (for example "3 malformed lines"). For Antigravity IDE and CLI sessions decoded from an unrecognized SQLite schema fingerprint, the header also shows Unverified schema. That badge means the session was decoded heuristically from a newer schema and may be incomplete.

AgentsView stores reading progress for the most recent 500 sessions in the current browser. When a transcript changes after you have read it, the sidebar shows an unread dot and the transcript places a New messages boundary at the first unread region. In newest-first order the same boundary is labeled Earlier messages. The marker clears after you traverse the new region; it is browser-local and is not synced through SQLite or PostgreSQL.

Message Layouts¶

Four layouts control how messages are rendered. Cycle between them with the l key or the layout button in the header, or pick one directly in Settings > Appearance:

Focused Transcript Mode¶

Focused mode strips intermediate tool calls, thinking blocks, and partial assistant messages, showing only user prompts and final assistant responses. This makes long sessions easier to read as a clean conversation transcript. Task notifications and stop hook feedback count as part of the turn they interrupt rather than as new prompts, so a session that waits on background agents still collapses to its prompts and final answers.

Toggle between Normal and Focused mode using the transcript mode button in the session header. The header adjusts responsively to fit the available space. The mode preference is saved in localStorage.

Message Display¶

Each message has a colored left border indicating role:

• Blue — user messages
• Purple — assistant messages

The header shows the role label, timestamp, and a copy button that appears on hover. Click it to copy the full message content to the clipboard — a checkmark confirms the copy for 1.5 seconds.

Inline <teammate-message> content and messages from teammate session ancestry are labeled Teammate, keeping peer-agent replies distinct from user prompts and ordinary subagent output.

Claude Code sessions also show a fork action on each message header when the local server can launch or return a command. Clicking it starts a new Claude run from the selected point by rendering the transcript through that message ordinal into a temporary prompt, starting claude in the session working directory, and removing the temporary prompt after launch. In read-only local mode the action copies the command instead of launching it; remote sessions cannot be forked from the browser.

Thinking Blocks¶

Assistant thinking blocks appear as collapsible sections with a purple left border. Toggle visibility for thinking blocks using the block-type filter in the header.

Tool Blocks¶

Tool invocations display as collapsible amber-bordered sections showing the tool name, arguments, and output. When collapsed, the header surfaces the most meaningful input field rather than the first line of the rendered content. TodoWrite shows the in-progress (or last) todo with a → prefix; TaskCreate shows the subject; TaskUpdate shows #<id> · <status> · <subject>; Skill shows the skill name; ToolSearch shows the first line of the query; and Task/Agent/subagent calls show the description (falling back to the prompt). For tools without a structured preview, the header falls back to the first line of content, the command/cmd (Bash), or the file_path/pattern (Read, Edit, Write, Glob).

When expanded, tool blocks display structured metadata tags extracted from the tool call input. For task management tools (TaskCreate, TaskUpdate, TaskGet), these tags show the task subject, status, and ID at a glance. Bash tool blocks show the full command text, including multi-line commands like heredocs that would otherwise be truncated. Tool result content is stored alongside the tool call when available, giving a complete view of input and output.

Expanded outputs start in Raw mode, which preserves the exact escaped text recorded by the agent. Switch to Formatted to render Markdown, including headings, lists, tables, and highlighted fenced code; HTML is sanitized before display. The mode changes presentation only—the stored result and copy button continue to use the raw output.

Hover or focus a tool block to reveal copy buttons for the structured input and, when present, the tool output.

Codex tool calls receive special formatting: bash commands, write_stdin operations, and apply_patch calls display with structured argument previews and categorized detail labels. Cursor ApplyPatch tool calls render as patch/diff content instead of plain JSON when the Cursor transcript exposes the patch payload.

When a Codex tool call has subagent result events — status updates captured during execution — an expandable history section appears below the tool output. Click it to see the full chronological timeline of status changes (e.g. "wait", "completed", "failed") with source and content for each event. The latest event summary is shown by default.

Subagent Linking¶

When a Task or Agent tool block is linked to a subagent session, it shows an expandable toggle. Click it to view the subagent's full transcript inline without leaving the parent session. Messages load on demand when the section is expanded, showing the complete subagent conversation with role labels and timestamps.

Tool Call Groups¶

Consecutive tool-only assistant messages are grouped into compact "N tool calls" sections with a gear icon and timestamp. Click to expand individual tool blocks within the group.

Code Blocks¶

Fenced code blocks render with language labels, monospace formatting, and horizontal scrolling for long lines. Hover or focus a code block to reveal a copy button in the corner; clicking it copies the raw code (no fences or language tag) to the clipboard.

As of 0.33.0, labeled code fences get syntax highlighting powered by Shiki. Twelve common languages are bundled — JavaScript, TypeScript, Python, Bash, JSON, YAML, Markdown, HTML, CSS, Rust, Go, and SQL (plus their usual aliases like py, sh, and yml). Unlabeled or unrecognized languages fall back to plain text. To keep large sessions fast, highlighting is skipped for blocks over 50 KB or 800 lines, and the highlighter loads lazily so it costs nothing until the first code fence renders.

Fenced code blocks labeled mermaid render as Mermaid diagrams in an interactive viewer with source-copy and expanded-view controls. If the Mermaid runtime cannot load, AgentsView keeps the escaped diagram source readable in the message. When in-session search is active, Mermaid fences render as source code so matches can be highlighted.

Block-Type Filtering¶

Click the filter icon in the message viewer header to open a dropdown that toggles visibility of seven content categories:

Turning off Code collapses each fenced block into an inline placeholder showing its language and an Expand button. Expand or collapse individual blocks without changing the global filter. Messages containing only code keep their placeholder. Filtered code stays out of in-session search; turn Code back on to include it.

System boundary cards are the compact rows that mark a session continuation or resume, an interrupted request, a task notification, or stop hook feedback. Hiding the category removes all of them; the rest of the transcript is unaffected.

All categories are visible by default. When any are hidden, a badge on the filter button shows the count of hidden types. Click Show all to restore visibility.

Sorting¶

Toggle between newest-first and oldest-first with the o key or the sort button in the header. The arrow icon indicates the current direction.

Message Navigation¶

• j or ↓ — next message
• k or ↑ — previous message
• Shift+J — next user prompt
• Shift+K — previous user prompt
• Click a message to select it (blue outline)

Prompt navigation follows the visible transcript, so it respects Focused mode and the active block-type filter.

In-Session Search¶

Press Cmd+F (or Ctrl+F) to open a search bar within the current session. Type to find matching text across all visible messages. The match count and current position are shown in the search bar.

Use the arrow buttons or Enter / Shift+Enter to jump between matches. The matching message scrolls into view and the search term is highlighted. Press Esc to close the search bar.

Click Show search results to open matching snippets grouped by message. Select a snippet to jump to its occurrence. The overview rail beside the transcript shows where matches appear throughout the session.

Search follows the transcript's active scope. Block-type filters (see Block-Type Filtering) and Focused mode both narrow what search can find: a hidden category contributes no matches, counts, badges, or highlights, and re-showing a category or returning to Normal mode makes that content searchable again without retyping the query. Folded content is still searched — collapsed tool output, thinking blocks, <details> sections, and rows that are not currently scrolled into view all match; only the current occurrence expands and scrolls into view. The match count, result list, and overview rail read the same filtered index, so they update immediately when a filter toggles during an active query.

Token Usage¶

The session detail header displays token usage when available, showing input and output token counts for the session. This gives a quick view of how much context the agent consumed and how much it generated.

As of 0.33.0, the header also shows the session's estimated cost next to the token summary, computed from the same data as agentsview session usage. Costs under a cent display as <$0.01, costs up to $100 with two decimals, and larger costs as whole dollars. The badge is hidden when the session has no token data or its models have no pricing.

When the selected session has explicit subagent descendants, the automatic header request adds rollup=true. A complete priced aggregate shows a localized total marker and the descendant count. If any contributing row is unpriced, the header keeps the root session's own cost when available and does not label it as a total. Sessions without explicit subagent descendants keep the existing badge.

As of 0.37.1, sessions with per-step usage rows also show a step count next to the token summary. Click it to expand a per-step breakdown: each row lists the prompt or usage event, the model that served it, its context size (input tokens plus cache reads and writes), its output tokens, and a per-step cost estimate when the model is priced. The rows come from the same session usage API with ?breakdown=true — see agentsview session usage.

For aggregate token usage and estimated cost reports across all sessions, see the Token Usage & Costs page and the agentsview report usage daily CLI command.

For a scriptable report on the current session, use agentsview session usage <id> or the matching GET /api/v1/sessions/{id}/usage REST endpoint.

Signal Panel¶

Click the health grade badge in the session header to open the signal panel for the current session. The panel shows:

• grade and numeric score
• outcome icon and confidence
• basis tags showing whether outcome, tool health, and context pressure contributed to the score
• compaction summary, including mid-task compactions
• penalty chips for the deductions that were applied

When a session does not have enough usable data, the panel shows a small empty state instead of a score. See Session Intelligence for the full model.

The same panel includes Observed tool sequences. Follow a failed or empty tool result through later retries, tool switches, and recovery, and open each call in the transcript. See Tool sequences for the evidence and timing details.

Session Vital Signs¶

Open Analysis from the session header to see Session Vitals in the right column. It shows elapsed turn time and measured tool durations.

The panel contains these sections, including experimental Recall when available:

• Session summary — repository and worktree context recorded by the trace, total wall-clock, turn count, tool call count, sub-agent count, and the slowest call as a clickable link that scrolls the conversation to that call. Live sessions show a running …+ indicator that ticks forward.
• Recall (experimental) — provenance-linked entries whose evidence comes from the current session. Evidence-range links jump to the supporting transcript message. An empty state appears when the local archive has no matching entries.
• Turn activity — each visible user prompt starts a window that ends at the next prompt or the session boundary. Bars separate measured tool execution from unattributed time, which has no measured phase boundaries. Thinking and response generation are not measured. Click a row to jump to its prompt in the transcript.
• Time spent — per-category aggregate bars across the normalized taxonomy (Read, Edit, Write, Bash, Grep, Glob, Task, Tool, Other, and other provider categories). Click a row to filter the rest of the panel to that category.
• Timeline — turns lane plus per-category lanes plus an activity lane, with a legend. Hover a turn segment to see its primary category and duration (e.g. Task · 2m); click to scroll the conversation to that turn.
• Calls — chronological list of tool calls with horizontal duration bars. Parallel tool_use runs are bracketed as a single group. Call details start collapsed for quicker transcript navigation. Sub-agent rows expand inline to show the child session's calls.

Tool durations come from paired execution events or a closed linked child session. A call without either source shows unknown; the summary and category totals show Not measured when no calls have measured durations. A measured zero remains 0ms. Categories remain available as filters even without timing. An open child needs a completed execution interval before its call can show a duration; otherwise it stays unknown until the child closes.

Session tool and category totals count only time within the session boundaries. Individual calls retain their full measured durations, including any time outside the parent session. Overlapping calls count once in the session total and once per category, so category totals can overlap each other.

Inline in the conversation column, tool headers show measured durations when available, and assistant messages show turn-summary lines. Tool labels are normalized across agents, so Codex's exec_command and Claude's Bash show up under the same "Bash" category in headers and in the Calls list.

Call duration bars in the Calls list are scaled relative to the longest call in scope, not total session wall-clock — so even in long sessions where any single call is a small fraction of the total, call-vs-call comparison stays legible. Very short calls floor at 4% width to remain visible.

Progressive Loading¶

Sessions with more than 3,000 messages load the most recent 1,000 messages first. Older pages load automatically as you scroll up. Smaller sessions load all messages at once.

Live Updates¶

When viewing an active session, AgentsView uses Server-Sent Events to stream new messages in real time. The message list updates incrementally — only new activity is fetched, rather than reloading the entire session — so updates arrive faster and with less overhead.

Follow Latest Message¶

As of 0.30.0, the session header has a Follow latest messages toggle. When active, the message list auto-scrolls to the newest message as updates stream in, so a long-running session stays pinned to the tail without manual scrolling. The toggle is also handy after a sync that rebuilt the session — it snaps back to the latest message once the re-rendered list settles.

Cancellation is automatic: scrolling up by hand or clicking a specific message turns follow mode off. Clicking the toggle again re-engages it and jumps to the latest message. The preference is persisted in localStorage, so a session you opened in follow mode comes back in follow mode.

Command Palette¶

Press Cmd+K (or Ctrl+K) to open the command palette — a full-screen search overlay.

Recent Sessions¶

With an empty query, the palette shows up to 10 recent sessions from the sidebar's current list. A short query filters that list by project, session name, or first message. Search begins at 3 characters, or 2 characters for Chinese, Japanese, and Korean text.

Search Modes¶

Search in one of three modes:

• Full text searches indexed message content with FTS5. It also matches session display names and first messages.
• Semantic ranks message content by meaning using the active embeddings index.
• Hybrid combines semantic and full-text rankings so that both conceptual and exact-term matches can surface.

The palette remembers the last mode you selected across openings and browser sessions. Results update after a 300ms typing pause.

Results are grouped by session — each session shows its best matching result. This prevents a single long session from dominating the results list. Full text also matches against session display names and first messages, so you can find sessions by title.

In Full text mode, use the sort toggle in the palette header to switch between Relevance (best matches first) and Recency (newest sessions first). Semantic and Hybrid use their backend rankings, so this toggle is hidden in those modes.

Semantic and Hybrid require an enabled [vector] configuration and an active embeddings index. If setup, index state, or the embeddings service prevents a search, the palette keeps the selected mode and shows actionable remediation rather than silently falling back to Full text.

Results use a compact row:

• Full text may show the session name and a sanitized snippet with highlighted search terms.
• Semantic and Hybrid lead with a plain-text matching snippet. Content search does not return a session name or highlight markup.
• All modes show an agent-colored dot, project and result time, and a copyable session ID.

Select a result to jump to that session and scroll directly to the matching message.

Project and date filters¶

Once your query is long enough to search, the palette shows project and date controls. Search starts with the sidebar's selected project; choose another project or All Projects without changing the sidebar.

Choose a relative period, calendar period, or custom dates. The filters apply to Full text, Semantic, and Hybrid searches. Closing the palette clears its date range; the next opening starts with the sidebar's current project again.

Keyboard Navigation¶

• ↑ / ↓ — navigate results
• Enter — select current result
• Esc — close palette

Session Management¶

Renaming Sessions¶

Double-click a session name in the sidebar to rename it inline. You can also right-click a session to open a context menu and select Rename. Press Enter to save or Escape to cancel. The custom name persists as a display_name in the database and overrides the default first-message title.

Trash¶

Press Del (or Backspace) with a session selected, or right-click and select Delete, to move it to the trash. An undo toast appears briefly to let you recover the session immediately. Trashed sessions are hidden from all listings and analytics.

Click More → Trash in the header navigation to view trashed sessions. From the trash page you can restore individual sessions or permanently delete them. Use Empty trash to permanently delete all trashed sessions at once.

Batch Selection¶

Click the Multi-select toggle in the sidebar header to enter selection mode. A checkbox appears on each session; click sessions to check them, or use All to select every visible session and Clear to deselect. The batch toolbar shows how many are selected and a Delete action that moves the whole selection to the trash at once. Toggle multi-select off to return to normal browsing.

Pinned Messages¶

Click the pin icon on any message header to pin it. Pinned messages are saved to the database and accessible from More → Pinned in the header navigation.

The pinned page shows a gallery-style grid of pinned messages. Each card shows the message content (expandable for long messages), the session and project it belongs to, and actions to copy the content, unpin, or navigate back to the source message in its session.

Session Resume Menu¶

Select a session and open Resume in the detail header. For supported local agents, the menu can launch the configured terminal, use the default terminal, or copy the exact resume command. Cursor resume resolves the original workspace path and passes it as --workspace to cursor agent --resume. The same menu can copy the session directory and open it in detected editors or file browsers.

Pi sessions use pi --session with the transcript path when available, or the native session ID. For Pi, Copy command includes the working directory so you can paste the complete command into a shell. Augure Code sessions use augure resume, and Open Interpreter sessions use interpreter resume. Copying a session's directory path also works when that directory has been deleted.

Local Codex sessions add Open in Codex Desktop, which deep-links to the stored thread. Local Claude sessions add Open in Claude Code, which opens a new Code session for the stored working directory; when the native Claude Desktop opener is detected, it remains available as a separate resume target.

For supported remote sessions, choose Copy command and paste the resume command into a shell on the machine that owns the transcript. Launching a terminal, opening an editor, and native agent desktop links are local-session actions.

The agentsview session list --resume and --active CLI modes use the same recent-activity signal to produce a compact terminal table for picking up in-flight work.

These actions let you quickly pick up where you left off without manually navigating to the project directory.

The agentsview:// URL Scheme¶

The desktop app registers the agentsview:// URL scheme, so other tools can open a session directly in the app:

open "agentsview://sessions/<session-id>"

An optional ?msg=<ordinal> or ?msg=last query scrolls to that message. If the app is already running, its window comes forward on the session; if not, the app starts and opens the session once the backend is ready. See the Session API guide for the full contract.

Session Export¶

Press e or open the export menu in the header to download the current session as a standalone HTML file. The exported file includes styled message rendering and works offline. The export includes a Normal / Focused radio toggle in the document header so the recipient can flip into focused mode — only user prompts and final assistant responses — without re-running the export.

The same menu also includes Copy markdown export link, which copies a URL for the session's markdown export endpoint. That link can be used in scripts, notes, or shared internal tooling when you want a text-oriented representation instead of the standalone HTML export. When the active session has a source file path, the menu also offers Copy source file path for quick handoff to another tool or terminal. The markdown export is particularly well-suited for handing session context to another agent.

The markdown export route is:

GET /api/v1/sessions/{id}/md

By default, it exports only the current session. Add the depth query parameter to inline descendants:

• ?depth=1 — include direct child sessions
• ?depth=all — include the full descendant tree

Subagent children are embedded inline near the tool call that spawned them. Other child sessions are appended after the parent transcript in <child_session> blocks. The markdown payload also includes XML-style tags for metadata, thinking blocks, tool calls, code blocks, and child-session boundaries.

Typical agent handoff flow:

curl "http://127.0.0.1:8080/api/v1/sessions/<session-id>/md?depth=all" \
  -o session-context.md

Then attach session-context.md to another agent run or paste its contents into a prompt so the next agent can inspect the full session tree without opening the AgentsView UI.

Publish to Gist¶

Press p or click the publish button to share a session via GitHub Gist. As of 0.33.0, the publish button is a dropdown with two entries: Publish public Gist and Publish secret Gist. The p shortcut publishes publicly.

AgentsView prefers your existing GitHub CLI login for local publishing. If no token is saved in AgentsView and AGENTSVIEW_GITHUB_TOKEN is not set, it runs gh auth token and uses that token to create the gist. Run gh auth login once if the GitHub CLI is not authenticated yet.

For remote or proxied AgentsView access, save a GitHub token in AgentsView before publishing. Remote requests do not use the server process environment or GitHub CLI credential as a fallback.

If neither a saved token, AGENTSVIEW_GITHUB_TOKEN, nor gh auth token is available for local publishing, the publish modal prompts for a GitHub personal access token with the gist scope. That token is saved to your config file and reused for future publishes.

After publishing, the modal shows two URLs:

• View URL — rendered view of the gist
• Gist URL — direct GitHub link

Both have copy buttons and an "Open in Browser" action.

Session Upload¶

Upload session JSONL files from other machines via the API:

curl -F "[email protected]" \
  "http://127.0.0.1:8080/api/v1/sessions/upload?project=myapp"

Uploaded files are stored in ~/.agentsview/uploads/ and synced into the database.

Replacing an existing session with fewer messages returns 409 Conflict without changing the stored transcript. To permit an intentional shorter rewrite, add allow_shorter=true to the upload query.

Keyboard Shortcuts¶

Press ? to see all shortcuts in a modal overlay.

Use Ctrl in place of Cmd on Windows and Linux. Most shortcuts are disabled when typing in an input field. Esc always works.

Settings¶

Click the gear icon in the header to open the Settings page. Settings are organized into sections:

Choose Español for Spanish. A browser set to Spanish selects it on first load; a saved language preference takes precedence.

Language, theme, high contrast, message colors, message layout, zoom, block visibility, and Date ranges preferences use local storage in the current browser or desktop webview profile. Each profile keeps its own choices. The optional zoom_level setting supplies a default when no local zoom or text-size preference exists.

Chart colors use the server-wide chart_palette setting in ~/.agentsview/config.toml. Agent directory overrides, terminal settings, the saved GitHub token, and the local server's remote-access authentication settings also use that file. Worktree mapping rules moved to the Data page and live in the local archive database. See Remote Access for details on the remote access settings.

About Dialog¶

Click the version number in the status bar or select About from the header menu to open the About dialog. It shows the current version, build date, git commit, and links to the changelog and GitHub repository.

Zoom¶

Settings > Appearance has one Zoom setting for the whole interface in both the browser and desktop app. It offers 67%, 75%, 80%, 90%, 100%, 110%, 120%, 125%, 130%, 150%, 175%, and 200%. Existing text-size preferences migrate to Zoom. A saved non-default zoom takes precedence. Otherwise, a saved non-default text size takes precedence over 100%.

To set the default for clients without a local preference, edit ~/.agentsview/config.toml and add zoom_level = 120. The field accepts the twelve values listed above. Restart the daemon and reload the client after a manual edit. Zoom changes in the interface stay local to that browser or desktop webview and do not write config.toml.

The desktop status bar and shortcuts change the same local setting. Use Cmd+Plus and Cmd+Minus, or Ctrl+Plus and Ctrl+Minus on Windows, to zoom in and out. Cmd+0, or Ctrl+0 on Windows, resets Zoom to 100%.

Theme¶

Click the theme toggle in the header or go to Settings > Appearance to switch between light and dark mode. The preference is saved and persists across sessions.

Settings > Appearance also offers a high-contrast mode for greater legibility. The theme and high-contrast preferences persist across sessions.

The Chart colors control selects the categorical palette used by the dashboard skill trend, Trends, and Usage charts:

• Agentsview: the project palette.
• Matplotlib: matplotlib's categorical families without their grays.
• Color-blind safe: Petroff's color sequences, chosen so series stay distinguishable with common forms of color blindness. Past the tenth series, colors repeat with a pattern: Usage bars, areas, and treemap tiles are hatched, then cross-hatched, then dotted, and Trends lines are dashed. Legends and lists show the same pattern.

This setting is server-wide rather than browser-local, so all clients connected to the same server use the same palette. You can change it even when the server reads from a read-only store such as PostgreSQL, ClickHouse, or DuckDB.

Message Colors¶

Message colors in Settings > Appearance sets the color of each message type: user messages, assistant text, thinking blocks, tool calls, and code blocks. It helps readers who cannot easily tell the default blue and purple apart.

• Color-blind safe applies hues that stay distinct with the common forms of color blindness: blue for user messages and vermillion for assistant text. The hues are the Okabe-Ito colors behind matplotlib's seaborn-v0_8-colorblind style. Thinking and code use darker versions of its pink and yellow, because the originals are too faint on light themes. The preset also turns on line patterns.
• Mark message types with line patterns gives each type its own bar: solid for user messages, double for assistant text, dotted for thinking, and dashed for tool calls. Code blocks get a dashed frame when they have a custom color. Types then differ by shape, not only by color. The patterns also stay visible in the Stream layout, which hides the role header.
• Each type has a color picker, a hex field, and quick-pick swatches. One color applies to light, dark, and high-contrast modes. The message background is a light tint of the color, and the label text is the color mixed toward the theme's text color.
• When a color would make label text hard to read (below 4.5:1) or the color bar hard to see (below 3:1) in any mode, the setting names the modes and the measured ratio. The color still applies, so you can decide.
• Reset restores one type's theme color. Reset to defaults restores every type and turns off patterns.

Iframe Embedding¶

When embedding AgentsView in an iframe, the parent page can control the theme via postMessage:

iframe.contentWindow.postMessage(
  { type: "theme:set", theme: "dark" },
  "*"
);

Accepted values for theme are "light" and "dark".

Sync¶

AgentsView automatically syncs session files on startup and watches for changes in real time. The sync status is shown in the status bar:

• Syncing indicator — green text showing progress percentage and phase (Scanning [project]... or parse progress)
• Last sync time — relative timestamp ("synced 2h ago") that updates automatically. Hover to see the exact sync timestamp.

Press r to trigger a manual sync. The sync button in the header shows a spinning animation while syncing.

The status bar also shows a version mismatch warning (red) if the frontend and backend versions differ. Click it to reload.

History from another machine¶

Attach a saved archive to browse a retired machine's Claude and Codex sessions beside your current ones. Choose a backup snapshot or an existing archive directory. Use machine_name to label a single-machine archive without changing its captured identity. Ordinary sync reads pending archive sources after local work. Once indexed, the history remains browsable with the drive disconnected. Reparsing requires the archive to be available again.

Full Resync¶

Click the gear icon in the header to open the Full Resync modal. This re-parses all session files from scratch using a non-destructive flow — existing session data is preserved and orphaned sessions (those no longer present on disk) are carried forward. This is useful after upgrading AgentsView or when sessions appear to be parsed incorrectly.

The modal shows live progress as sessions are processed:

1. Confirm — describes what the resync does, with Start and Cancel buttons
2. Progress — live counter and progress bar ("Syncing X / Y sessions..."). The modal stays open until the resync finishes.
3. Done — shows synced, skipped, and total session counts
4. Error — if the resync fails, shows the error with Retry and Close buttons