kenn-io--agentsview/docs/usage.md

title, description

title	description
Usage Guide	Complete guide to the AgentsView web interface

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

When you open AgentsView with no session selected, you see the analytics dashboard. It provides a high-level overview of your agent activity across all projects.

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, Usage page, 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. Click refresh, or change the date range, to pull the latest numbers.

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:

Card	Description
Sessions	Total session count
Messages	Total message count
Projects	Number of active projects
Active Days	Days with at least one session
Messages/Session	Average with median and p90
Concentration	Most active project and its share

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 Insights, 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.

!!! note "Dashboard-only scope" The model filter applies only to the analytics dashboard. The Session Insights page and the session list are not scoped by it, so a model selected here does not silently narrow those views. The Usage page keeps its own separate model filter.

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

A stacked chart showing messages, sessions, tool calls, and thinking blocks over time. Toggle between daily, weekly, and monthly granularity. Includes breakdown by agent.

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.

Top Skills

The Top Skills panel ranks skill-backed tool calls by call count, session count, recency, agent mix, project mix, and week-by-week trend. It 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 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.

---

Session Insights

AgentsView can generate AI-powered summaries and analysis of your coding sessions using Claude, Codex, Copilot, or Gemini. Click More → Insights in the header navigation to open the Insights page, where you can generate daily activity digests, multi-day summaries, and deeper analyses of your agent workflow patterns — scoped by project or across everything.

See the Session Insights page for full documentation.

---

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 — display name if set, otherwise first message text. OpenCode sessions use their native session titles. As of 0.27.0, Copilot CLI sessions use the name field from the session's workspace.yaml when present, falling back to the first user message otherwise. 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 — several agents record a session title themselves (Claude Code's /rename, Codex session_index.jsonl thread names, Claude.ai and ChatGPT conversation names, Forge, Hermes, Kiro, Piebald, Cortex Code, and Command Code's .meta.json titles). As of 0.33.0, the sidebar shows these titles automatically when present. 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.
• 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

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.

State	Indicator	Meaning
Working	Pulsing green	Last write within the last minute
Waiting	Tan speech bubble	Session ended on the agent's "your turn" stop reason and was active in the last 10 minutes
Idle	Muted green	1–10 minutes idle, not awaiting user input
Stale	Amber	10–60 minutes idle and last assistant message has an unresolved tool call (or the session file was truncated mid-write)
Unclean	Red	Same flagged state as Stale, but idle for more than an hour
Quiet	Hidden	Cleanly-ended sessions older than 10 minutes; no dot is rendered

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:

• 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 names. 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.
• 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

Each session has a shareable URL. Click the session ID in the detail header to copy the link, or use the URL bar directly:

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

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

URL Filters

URL parameters are supported for direct linking:

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

Available URL filters:

Parameter	Value
project	comma-separated project names
agent	comma-separated agent ids
machine	comma-separated machine names
termination	comma-separated status tiers — any of active, stale, unclean, clean, awaiting_user
date, date_from, date_to	ISO date or activity-overlap range bounds
active_since	true to limit to the last 24 hours
min_messages, max_messages	numeric message count bounds
min_user_messages	numeric user-message threshold
include_one_shot	false to hide single-turn sessions (default)
include_automated	true to include automated sessions
exclude_project	comma-separated projects to hide (e.g. unknown)

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.

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.

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:

Layout	Description
Default	Full card layout with colored borders and spacing
Compact	Condensed view with minimal spacing
Stream	Continuous flow optimized for reading
Skim	Collapses tool calls to summary headers for fast skimming

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.

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.

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.

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 five content categories:

Category	What It Controls
User	User messages
Assistant	Assistant responses
Thinking	Thinking/reasoning blocks
Tool	Tool call blocks
Code	Code blocks

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
• Click a message to select it (blue outline)

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.

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.

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 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.

Session Vital Signs

The right column of an open session shows a Session Vital Signs panel with timing data derived from the message timestamps. Toggle it from the session header.

It has four stacked sections:

• Session summary — 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.
• Time spent — per-category aggregate bars across the normalized taxonomy (Read, Edit, Write, Bash, Grep, Glob, Task, Tool, Other, plus a Mixed bucket for turns split across 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. Sub-agent rows expand inline to show the child session's calls.

Inline in the conversation column, each ToolBlock header gets a duration badge, and each assistant message gets a turn-summary line ("turn 2m 18s · 3 calls"). Parallel non-sub-agent calls render with a striped bar and a ≤duration upper bound — the JSONL source has only one timestamp per assistant message, so per-call precision inside parallel groups isn't recoverable for non-sub-agent calls. 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 or short query (under 3 characters), the palette shows your 10 most recent sessions. Type to filter by project name or first message.

Search Modes

Type 3 or more characters to 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.

!!! tip For deeper searches across full transcripts — including tool inputs, tool result content, and regex patterns — use the agentsview session search CLI or the GET /api/v1/search/content HTTP endpoint added in 0.30.0. The command palette indexes message bodies via FTS5 for fast scoring; the content-search endpoints add substring and regex modes and cover tool I/O as well.

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.

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

Right-click a session in the sidebar to open a context menu with three resume actions:

• Reopen — reopen the session in the agent that created it
• Terminal — launch a terminal in the session's working directory
• Open Directory — open the session's working directory in Finder (macOS) or Explorer (Windows)

GitHub Copilot CLI and Cursor sessions also appear in the resume dropdown. Cursor resume resolves the original workspace path automatically and passes it as --workspace to cursor agent --resume.

For Claude sessions on macOS, a Claude Desktop option appears at the bottom of the resume menu. It opens the session in Claude Desktop's Code tab via the claude://resume URL scheme.

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.

---

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. As of 0.30.0, the export ships with 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.

!!! warning Secret gists are unlisted, not access-controlled: they don't appear in your public gist list or in search, but anyone who has the URL can read them.

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 "file=@session.jsonl" \
  "http://127.0.0.1:8080/api/v1/sessions/upload?project=myapp"

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

---

Keyboard Shortcuts

Press ? to see all shortcuts in a modal overlay.

Key	Action
Cmd+K	Open command palette
Cmd+F	Search within current session
Esc	Close modal / deselect session
j / ↓	Next message
k / ↑	Previous message
]	Next session
[	Previous session
o	Toggle sort order
l	Cycle message layout
s	Star / unstar current session
Del	Delete / archive selected session
r	Trigger sync
e	Export session
p	Publish to Gist
?	Show shortcuts

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:

Section	What You Can Configure
Language	Interface language (English, Simplified Chinese, Traditional Chinese, or Korean)
Appearance	Theme (light/dark), high-contrast mode, message layout, text size, block visibility, desktop zoom level
Date ranges	Browser-local checkbox for linking date selections across Sessions, Usage, Activity, Trends, and Insights
Agent Directories	Custom paths for each agent's session files. For Devin CLI, point at the local root that contains cli/ (for example a redacted .../Application Support/devin path), not copied config or OAuth files.
Terminal	Default terminal emulator for session resume
Worktree Mappings	Map worktree paths back to their main project (see Worktree Project Mappings)
GitHub	Personal access token for Gist publishing
Remote Access	Remote connections toggle, auth token, connect to remote server

Language, Appearance, and Date ranges preferences are stored in the browser and do not write ~/.agentsview/config.toml. Agent directory overrides, terminal settings, the saved GitHub token, and the local server's remote-access authentication settings use ~/.agentsview/config.toml. Worktree Mappings live separately 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.

---

Desktop Zoom

In the desktop app, use Cmd+Plus and Cmd+Minus (or Ctrl+Plus / Ctrl+Minus on Windows) to zoom in and out. Cmd+0 resets to the default zoom level. The zoom level can also be set in the Settings page under the Appearance tab.

---

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 and a text size control (90–130%) that scales message and interface text. Both preferences are saved and persist across sessions.

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.

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