Skip to content

Latest commit

 

History

History
1111 lines (935 loc) · 64.7 KB

session-api.md

File metadata and controls

1111 lines (935 loc) · 64.7 KB
title Session API
description Programmatic access to session data via the agentsview session CLI and REST endpoints

The agentsview session command group is a stable, programmatic surface for reading and writing session data. It is designed for shell scripts, automation agents, and CI jobs that need structured output rather than the web UI.

When an AgentsView daemon is running, the CLI proxies supported operations to it over HTTP. On a cold archive, read-only commands open local SQLite directly in read-only mode, while commands that need fresh data or need to write start or reuse the detached local daemon. This keeps one-off reads fast and keeps SQLite writes owned by one process.

Quick examples

# Search parsed message/tool content without scanning raw JSONL files.
agentsview session search "database timeout" --json --limit 10

# Recover recent context for one project, then fetch the first page
# of messages from a selected session.
agentsview session list --project myapp --limit 5 --json
agentsview session messages <session-id> --from 0 --limit 20 --json

# Query an already-running daemon explicitly.
agentsview session list --server http://127.0.0.1:8080 --json

# Read from configured PostgreSQL instead of local SQLite.
agentsview session search "regression" --pg --json

Stability

  • Additive-only. New fields may appear at any time. Existing fields are never renamed or removed.
  • Types are stable. A field that is a string stays a string.
  • Unknown fields are safe to ignore. Well-behaved consumers tolerate forward-compatible additions.

HTTP and CLI share DTOs for bounded responses (same JSON object). The CLI watch command emits NDJSON whose lines mirror the underlying SSE events.

Transport

Detection uses kit daemon runtime records in AGENTSVIEW_DATA_DIR and the daemon ping endpoint. Runtime records include service and API metadata so incompatible or read-only daemons are not mistaken for a writable local archive owner.

  • If --server <url> is set, supported commands proxy to that daemon over HTTP. --server and --pg are mutually exclusive. The local config auth_token is not sent to explicit URLs; set AGENTSVIEW_SERVER_TOKEN or pass --server-token-file <path> when that remote daemon requires auth.
  • If no explicit server is set and a local daemon is running, read and write commands proxy to it over HTTP.
  • If a pg serve daemon is running (read-only), read commands proxy to it but session sync refuses with a clear error.
  • If both a writable local daemon and a pg serve daemon advertise the same data directory, the writable one wins so sync/write operations don't silently land on a read-only target.
  • If no daemon is running, read-only commands open the local archive directly in read-only mode.
  • If a command requires fresh data or needs to write and no daemon is running, the CLI starts agentsview serve --background, waits for readiness, and proxies the operation to that daemon.
  • If AGENTSVIEW_NO_DAEMON=1 is set, the CLI never auto-starts a daemon. Read commands use direct read-only SQLite. Write commands run directly only after acquiring the per-data-dir write-owner lock.
  • If a writable daemon is known to own the local archive but is not reachable, write commands refuse instead of opening SQLite as a second writer. Read commands may still fall back to direct read-only SQLite.
  • session export always runs locally regardless of daemon state, and rejects --server, --pg, and --format/--json because it streams raw source bytes.

When a discovered local daemon requires auth (require_auth: true), the CLI attaches Authorization: Bearer <token> using the auth_token from the shared config. Explicit --server URLs are different: they only receive a bearer token supplied with AGENTSVIEW_SERVER_TOKEN or --server-token-file <path>, so a local daemon token is not leaked to arbitrary remote URLs. Prefer --server-token-file for long-running commands and shared hosts so the token does not appear in process arguments.

--pg opens the configured PostgreSQL read store directly. It is useful for automation running away from the UI server, but it is read-only: session sync and session export reject it. If AGENTSVIEW_PG_URL or [pg].url is configured, read commands still use local SQLite unless --pg is supplied.

Common flags

Flag Description
--format human|json Output format. Default human.
--json Alias for --format json.
--server <url> Explicit daemon URL for HTTP-backed operations.
--server-token-file <path> Bearer token file for an explicit --server URL.
--machine <value> Filter bare Codebuff/Freebuff timestamp resolution to a single machine identity (local, a name, or *). Default local. session get only; canonical IDs and other agents are unaffected.
--pg Read from configured PostgreSQL instead of SQLite.

Shared metadata endpoints

The web UI and generated API clients use shared metadata endpoints for filter options:

GET /api/v1/projects
GET /api/v1/machines
GET /api/v1/branches
GET /api/v1/agents

GET /api/v1/branches returns distinct (project, branch) pairs plus an opaque token field:

{
  "branches": [
    {
      "project": "myapp",
      "branch": "main",
      "token": "..."
    }
  ]
}

Pass the returned token back as the git_branch query parameter on branch-aware endpoints. Treat it as opaque and URL-encode it in manual HTTP calls. The token is scoped by both project and branch, so app-a/main and app-b/main remain distinct, and an empty branch remains distinct from a literal unknown branch.

Commands

agentsview session get

Return session metadata plus computed signal fields. Shape matches GET /api/v1/sessions/{id}.

agentsview session get <id> [--format json]

Bare timestamps on remote stores. Codebuff/Freebuff sessions live as <agent>:<project>:<timestamp> canonical IDs; a bare timestamp (e.g. 2026-07-16T00-09-00.236Z) is not a canonical ID. Against the local archive the CLI resolves a bare timestamp to its canonical ID by walking the configured codebuff/freebuff roots, gated by --machine (default local). Against a remote store (--server, --pg) a bare Codebuff/Freebuff timestamp is rejected with an explicit error pointing at session list, because a bare timestamp is intrinsically ambiguous across machines and projects. The rejection is scoped to the Codebuff/Freebuff timestamp shape; bare IDs that are not timestamps (Codex / Copilot / Gemini UUIDs, etc.) are unaffected and continue to resolve via the registered agent prefix retry on remote reads, the same way they do locally. Always pass the full canonical ID on remote reads when one is known:

# Local reads: bare timestamp OK (--machine=local by default).
agentsview session get 2026-07-16T00-09-00.236Z
agentsview session get 2026-07-16T00-09-00.236Z --machine=*

# Remote reads: pass the canonical ID from `session list`.
agentsview session get codebuff:myproject:1704067200 --pg
agentsview session get freebuff:myproject:1704067200 --pg
agentsview session get host~codebuff:myproject:1704067200 --server http://remote
agentsview session get host~freebuff:myproject:1704067200 --server http://remote
{
  "id": "abc-123",
  "project": "myapp",
  "machine": "workstation",
  "agent": "claude",
  "first_message": "...",
  "display_name": "...",
  "git_branch": "main",
  "started_at": "2026-04-18T12:00:00Z",
  "ended_at": "2026-04-18T13:00:00Z",
  "message_count": 42,
  "user_message_count": 7,
  "health_score": 85,
  "health_grade": "A",
  "outcome": "completed",
  "health_score_basis": ["..."],
  "health_penalties": {"tool_retries": 5},
  "parser_malformed_lines": 3,
  "secret_leak_count": 0
}

health_score_basis and health_penalties are populated when health_score is non-null. Both HTTP and CLI surfaces return them.

git_branch is the branch captured at sync time when the parser or source metadata exposes it; sessions with no recorded branch omit the field. parser_malformed_lines counts the malformed source lines a parser skipped while still recovering the session and is omitted when zero. Antigravity detail responses may also include decode_confidence; the value low means the session came from an unrecognized Antigravity schema fingerprint and was decoded heuristically.

secret_leak_count (added in 0.30.0) counts definite-tier findings from secret scanning and is stamped inline during sync. Candidate-tier findings only show up after an explicit agentsview secrets scan --backfill and do not contribute to this count.


agentsview session list

Filtered session list. Response shape matches GET /api/v1/sessions.

agentsview session list [flags]
{
  "sessions": [ ... ],
  "next_cursor": "...",
  "total": 42
}

One-shot and automated sessions are excluded by default. When the first CLI page hides any, session list writes an advisory to stderr with the hidden count for each category and the --include-one-shot or --include-automated flag that reveals it. Human and JSON stdout are unchanged, so redirecting or piping structured output remains safe. The JSON total continues to describe the filtered result, not the excluded sessions. Use the --include-* flags to opt back in.

Date filters match a session when its activity window overlaps the selected date or range. Sessions that start before midnight and remain active after it therefore appear on both dates.

Flag HTTP param Notes
--project project string
--exclude-project exclude_project string
--machine machine string
— git_branch opaque token from GET /api/v1/branches
--agent agent string
--date date YYYY-MM-DD
--date-from date_from YYYY-MM-DD
--date-to date_to YYYY-MM-DD
--active-since active_since RFC3339 timestamp
--since active_since Relative — Nh hours, Nd days, Nw weeks, Nm calendar months (not minutes), Ny years — or YYYY-MM-DD; resolved against now and mutually exclusive with --active-since
--resume active_since CLI shortcut for sessions active in the last 15 minutes
--active active_since Alias for --resume
--min-messages min_messages int
--max-messages max_messages int
--min-user-messages min_user_messages int
--include-one-shot include_one_shot bool
--include-automated include_automated bool
--include-children include_children bool
— include_source bool; include source file paths, which are hidden by default
--outcome outcome comma-separated
--health-grade health_grade comma-separated
--min-tool-failures min_tool_failures int; 0 is a meaningful filter
--has-secret has_secret bool — only sessions with at least one definite secret finding
--sort order_by comma-separated keys; optional :asc / :desc suffix per key
--reverse, -r descending flips the default direction for unsuffixed sort keys
--cursor cursor opaque string from prior response
--limit limit int; default 200, max 500

Sort keys are recent, started, messages, user-messages, output-tokens, peak-context, failures, retries, edit-churn, compactions, context-pressure, health, secrets, and id. recent defaults descending; the other keys default ascending unless --reverse, descending=true, or an explicit suffix overrides them.

Human CLI output is formatted for resuming work: it shows the full session ID, age, agent, project, branch, message count, title, and working directory, with a marker on sessions active in the last 15 minutes. --resume and --active set active_since to that 15-minute window unless --active-since is supplied explicitly. HTTP callers should pass active_since directly.

Examples:

agentsview session list --resume
agentsview session list --sort messages:desc,started:asc
agentsview session list --sort health --reverse

agentsview session messages

Return a window of messages. Response shape matches GET /api/v1/sessions/{id}/messages.

agentsview session messages <id> [--from N] [--limit N] [--direction asc|desc]
agentsview session messages <id> --around N [--before N] [--after N] [--role user,assistant]

--from is pointer-valued at the service layer: omitting it means "start at the beginning" for ascending and "start at the newest page" for descending; an explicit --from 0 means "start at ordinal 0" in both directions. --direction is validated to asc or desc.

Window and role flags (see Semantic Search for the cursor-follow workflow they support):

Flag HTTP param Notes
--around around Center a window on this ordinal; mutually exclusive with --from/--direction
--before before Messages before the anchor (default 5); requires --around
--after after Messages after the anchor (default 5); requires --around
--role roles Comma-separated roles to include, e.g. user,assistant

With a --role filter, --before/--after count filtered messages; the anchor message is always included. Responses report the window's first_ordinal/last_ordinal so callers can continue paging with --from <last_ordinal + 1>.

{
  "messages": [
    {
      "ordinal": 0,
      "role": "user",
      "content": "...",
      "thinking_text": "",
      "timestamp": "2026-04-18T12:00:00Z",
      "is_system": false,
      "source_type": "user",
      "source_subtype": "",
      "has_thinking": false,
      "has_tool_use": false
    }
  ],
  "count": 1
}

thinking_text holds the concatenated text of any thinking blocks the agent emitted, separated from the flattened content which still contains inline [Thinking]...[/Thinking] markers for UI rendering.

Promoted source_subtype values on is_system: true messages: continuation, resume, interrupted, task_notification, stop_hook, compact_boundary.


agentsview session tool-calls

Chronological flattened list of tool invocations.

agentsview session tool-calls <id>
{
  "tool_calls": [
    {
      "ordinal": 3,
      "timestamp": "2026-04-18T12:05:00Z",
      "tool_use_id": "toolu_01abc...",
      "tool_name": "Bash",
      "category": "Bash",
      "input_json": "{\"command\":\"ls\"}",
      "skill_name": "",
      "subagent_session_id": "",
      "result_length": 128
    }
  ],
  "count": 1
}

input_json is a string — usually a serialized JSON object but may be a plain string (e.g. "echo hello world" from Codex).


POST /api/v1/sessions/{id}/resume

Resume a local session in its native agent, or return the command that would be launched. This is an HTTP-only surface used by the web UI's resume menu.

POST /api/v1/sessions/{id}/resume

Request body:

{
  "skip_permissions": false,
  "fork_session": false,
  "from_ordinal": 17,
  "command_only": false,
  "opener_id": ""
}

Response:

{
  "launched": true,
  "terminal": "Terminal",
  "command": "cd /repo && claude --resume abc-123",
  "cwd": "/repo"
}

command_only: true returns the command without launching a terminal. When a launch is attempted but fails, the response still includes the command with launched: false and an error code of no_terminal_found or launch_failed. Read-only local mode can still return commands, but remote sessions and read-only remote serving cannot launch local programs.

For Claude Code sessions, setting fork_session: true without from_ordinal appends Claude's native --fork-session flag to the normal resume command. Setting both fork_session: true and from_ordinal creates a message-point fork: AgentsView renders the transcript through that message ordinal into a temporary prompt and runs claude < prompt from the resolved session working directory. Message-point forks are Claude-only, require fork_session, reject opener_id, and return 404 when the ordinal is not present.


The agentsview:// URL scheme

The desktop app registers the agentsview:// URL scheme, letting external tools open a session in the app without going through HTTP:

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

Contract:

  • Only agentsview://sessions/<session-id> URLs are accepted. The session id must be a single path segment; percent-encode reserved characters. Anything else is logged to the desktop log and ignored.
  • An optional ?msg=<ordinal> or ?msg=last query scrolls to that message. Other query parameters are dropped.
  • If the app is running, its window is focused and navigated to the session. If not, the app launches and opens the session once its backend is ready. On Windows and Linux a second launch forwards its URL to the running instance and exits.
  • Callers can detect a missing handler because open (macOS) and equivalent launchers exit non-zero when no app claims the scheme; fall back to the web UI at http://<host>:<port>/sessions/<session-id> in that case.

The scheme is registered by the installed desktop app; it is not available when only the CLI or server is installed.


agentsview session export

Stream the raw session source file to stdout. This is a local-only filesystem helper: the source file path is resolved from the local SQLite archive, never from any daemon. Both --server and --format/--json are rejected with an error — the command also rejects --pg. It streams raw bytes, so structured-output and remote-store flags don't apply.

agentsview session export <id>

Exit states:

State Behavior
Session in local archive, file on disk Streams bytes verbatim
Session in local archive, file missing Exit 1: error prefixed source file not found
Session in local archive, path empty Exit 1: source file not found for session <id>
Session not in local archive Exit 1: session not in local archive: <id>

For a DB-derived export (HTML or markdown) use the HTTP endpoints /api/v1/sessions/{id}/export or /api/v1/sessions/{id}/md.

Markdown export accepts an optional depth query parameter:

  • omitted: root session only
  • depth=1: include direct child/subagent sessions
  • depth=all: recurse through the child-session tree

Any other depth value is rejected.


agentsview session sync

Parse and insert a single session. Blocks until indexing and signal computation complete. JSON output is the SessionDetail of the synced session; human output is one line: synced: <id>.

agentsview session sync <path-or-id>

Argument resolution: if the argument is an existing filesystem path, it is treated as a raw JSONL file to parse. Otherwise it is treated as a session ID for re-parse.

With --server <url>, path-shaped arguments such as /var/log/agent/session.jsonl or ./session.jsonl are sent to the remote daemon as paths and resolved on that daemon host. Bare values without path separators are treated as session IDs.

When a single JSONL maps to more than one session (for example a Claude transcript with forked/resumed branches), session sync <path> refuses with an error that lists every candidate id. The contract is "one session in, one SessionDetail back", so the CLI never picks arbitrarily.

At that point the file has already been parsed and every candidate session written to the local archive — the ambiguity check runs after the sync engine finishes. Re-run session sync <id> with the specific session you want; the <id> form resolves the file path from the archive, so it only works for sessions already present there.

  • session sync uses a writable local daemon when one is running, or starts a detached daemon when no compatible daemon is running. It then proxies to POST /api/v1/sessions/sync so parsing and signal computation remain daemon-owned.
  • If a pg serve daemon is running (read-only), sync refuses with a clear error.
  • If AGENTSVIEW_NO_DAEMON=1 is set, the CLI runs the sync in-process only after acquiring the local write-owner lock.

agentsview session watch

Stream NDJSON events as the session updates. Each line is a small object that wraps an SSE event.

agentsview session watch <id>
{"event":"session_updated","data":"abc-123"}
{"event":"heartbeat","data":"2026-04-18T12:05:00Z"}

Recognized event values today: session_updated, heartbeat. New events may be added; consumers should ignore unknown events. The command runs until interrupted (Ctrl+C) or the context is cancelled. Like session export, it streams a fixed format and rejects --format/--json.

Watch validates the session id before opening the stream. An unknown id fails fast with a watch: session not found: <id> error and non-zero exit instead of producing an indefinite heartbeat stream — typos in automation scripts surface immediately. When proxied to a daemon, the same condition surfaces as HTTP 404 at the transport layer before being translated to the CLI error.


agentsview session search

Substring, RE2 regex, or FTS5 search across message bodies, tool inputs, and tool result content. Response shape matches GET /api/v1/search/content.

agentsview session search <pattern> [flags]
{
  "matches": [
    {
      "session_id": "abc-123",
      "project": "myapp",
      "ordinal": 17,
      "ordinal_range": [12, 24],
      "location": "tool_result",
      "tool_name": "Bash",
      "snippet": "...connecting to db with token ***REDACTED***..."
    }
  ]
}

One-shot, automated, and subagent sessions are excluded by default; opt back in with --include-one-shot, --include-automated, or --include-children.

Flag HTTP param Notes
--regex mode=regex Treat pattern as an RE2 regex
--fts mode=fts Tokenized FTS5 search; messages-only
--semantic mode=semantic Vector search over user/assistant messages; messages-only — see Semantic Search
--hybrid mode=hybrid Semantic + FTS reciprocal rank fusion; messages-only — see Semantic Search
--scope scope top, all (default), or subordinate — semantic/hybrid only; supersedes include_children in those modes
--context context int — N messages of context before/after each match (max 10)
--in in Comma-separated: messages,tool_input,tool_result (default all)
--exclude-system exclude_system Drop system messages from the scan
--reveal reveal Show full secret values (localhost-only; warning to stderr)
--project project string
--exclude-project exclude_project string
--machine machine string
— git_branch opaque token from GET /api/v1/branches
--agent agent string
--date date YYYY-MM-DD
--date-from date_from YYYY-MM-DD
--date-to date_to YYYY-MM-DD
--active-since active_since RFC3339 timestamp
--since active_since Relative — Nh hours, Nd days, Nw weeks, Nm calendar months (not minutes), Ny years — or YYYY-MM-DD; resolved against now and mutually exclusive with --active-since
--include-children include_children bool
--include-automated include_automated bool
--include-one-shot include_one_shot bool
--exclude-session exclude_session repeatable session ID to drop before --limit
--limit limit int; default 50, max 500
--cursor cursor int — pagination cursor from a previous response

--regex, --fts, --semantic, and --hybrid are mutually exclusive. --fts is the fastest mode on large archives but only searches message bodies; substring (the default) and regex modes also walk tool_calls.input_json, tool_calls.result_content, and the tool_result_events rows. --semantic and --hybrid require an embedding index and return a single ranked page (--cursor is rejected) — see Semantic Search for setup, scoring, and limitations.

Every match, in every mode, carries the conversation-unit citation described in Hit shape: ordinal_range — [start, end] of the conversation unit containing the match, always present, [ordinal, ordinal] when the match is its own unit — plus the lineage fields subordinate, relationship, parent_session_id, and is_sidechain. ordinal stays the anchor (the exact matched message) in every mode. Only the lineage fields are omitempty: a missing key unambiguously means top-level with no lineage, while ordinal_range is never omitted, even at [0, 0]. score is the one field only --semantic/--hybrid emit. --scope is rejected outside --semantic/--hybrid; in those modes it supersedes --include-children, and subagent/fork-typed or parent-linked sessions are exempt from the default one-shot exclusion.

Snippets carry ~60 characters of context on each side of the match, snapped to rune boundaries. Any substring that matches the secret scanner rule set is masked unless --reveal is passed. The same masking applies to the HTTP endpoint when called from a remote origin — reveal=true is only honored on a localhost-bound daemon.


agentsview session usage

Per-session token usage and cost estimate. Output shape is stable for the fields shown below; new fields may be added.

Totals cover the named session and every subagent transcript spawned beneath it. Claude Code writes each Task-tool subagent to its own file under <session>/subagents/, which agentsview ingests as a separate session; reporting only the parent's own rows understated its cost by up to 77% in real sessions. Attribution happens at read time — no rollup is persisted, no child row is duplicated under the parent, and daily/activity aggregates (which already count subagent sessions as first-class spend) are unaffected. Pass --own-only to report just the named transcript's rows, which is the pre-0.40.0 output.

The REST endpoint is GET /api/v1/sessions/{id}/usage, and it is own-session by default. Two query params widen it, and they are not composable: if both are passed, rollup=true takes precedence and subagents is ignored for that request.

  • ?subagents=true folds descendant usage into cost, total_output_tokens, models, breakdown, and breakdown_count, and adds subagent_count. This is what the CLI requests.
  • ?rollup=true keeps the totals own-session and reports the combined cost in the separate rollup_* fields below. The session detail header uses this form. When both rollup=true and subagents=true are passed, the handler returns from the rollup branch first, so subagents has no effect.
agentsview session usage <id> [--format json] [--own-only]
{
  "session_id": "abc-123",
  "agent": "claude",
  "project": "myapp",
  "total_output_tokens": 15230,
  "peak_context_tokens": 84000,
  "has_token_data": true,
  "cost": {"microdollars": 2410000},
  "has_cost": true,
  "cost_usd": 2.41,
  "cost_source": "computed",
  "models": ["claude-opus-4-7"],
  "unpriced_models": [],
  "breakdown_count": 42,
  "subagent_count": 2,
  "breakdown": [
    {
      "ordinal": 1,
      "message_ordinal": 0,
      "source": "message",
      "label": "Prompt 1",
      "timestamp": "2026-07-08T14:03:21Z",
      "model": "claude-opus-4-7",
      "input_tokens": 1200,
      "output_tokens": 640,
      "cache_creation_input_tokens": 0,
      "cache_read_input_tokens": 43000,
      "web_search_requests": 2,
      "cost": {"microdollars": 580000},
      "has_cost": true
    },
    {
      "ordinal": 2,
      "message_ordinal": 4,
      "source": "message",
      "label": "Prompt 5",
      "timestamp": "2026-07-08T14:05:02Z",
      "model": "claude-opus-4-7",
      "subagent_session_id": "agent-9f2c",
      "input_tokens": 800,
      "output_tokens": 310,
      "cache_creation_input_tokens": 0,
      "cache_read_input_tokens": 12000,
      "cost": {"microdollars": 190000},
      "has_cost": true
    }
  ],
  "server_running": false
}
Field Notes
total_output_tokens Generated output tokens across the session and its included subagents, deduplicated the same way cost is (see below)
peak_context_tokens Highest context-token count observed in any included session; peaks are high-water marks, so they are maxed rather than summed
has_token_data false when no included session has token usage
cost Model-pricing estimate as an integer microdollar object; zero when has_cost is false
has_cost false if any contributing row is unpriced — never reports a partial total as complete
cost_usd Deprecated compatibility alias for cost.microdollars / 1e6, present only when has_cost is true; will be removed in a future release, use cost.microdollars instead
cost_source Omitted without a complete cost; reported for an authoritative session total, otherwise computed, reported, or mixed for the contributing rows
ai_credits Omitted unless the priced agent uses AI Credits; derived from cost_usd at 100 credits per dollar
models Models with contributing usage, sorted by model name
unpriced_models Omitted from JSON when empty; lists models seen but missing from pricing
breakdown_count Number of deduplicated per-step usage rows across all included sessions; always populated
subagent_count Number of subagent descendant sessions folded in; omitted when zero, so own-session results are byte-identical to before
breakdown Per-step usage rows ordered by timestamp across all included sessions (the queried session wins ties); when a reported session total exists, row costs are estimated allocations that sum to it; CLI JSON always includes them (added in 0.37.1)
server_running true when the report came from an already-running daemon
rollup_cost REST only, with rollup=true; integer microdollar object present only when has_rollup_cost is true, carrying the complete cost across the root and explicit subagent descendants
has_rollup_cost REST only, with rollup=true; true only when at least one contributing row exists and every contributing row is priced
rollup_subagent_count REST only, with rollup=true; count of reachable explicit subagent descendants, including those without usage rows

Claude Code echoes some parent turns into a subagent's sidechain transcript, so the same message can appear in two sessions. Every combined figure counts it once: cost, total_output_tokens, breakdown, and breakdown_count are all derived from one deduplicated row set, so they agree with each other and with the day aggregates. This is why the combined total_output_tokens can be lower than the sum of the included sessions' individual total_output_tokens — each of those is derived from its own transcript in isolation and still contains the echo. A session with no per-message usage rows contributes its session-level total instead, since it has nothing to deduplicate against.

Each breakdown row carries the fields shown in the example:

Row field Notes
ordinal 1-based position of the row in the deduplicated usage stream
message_ordinal Ordinal of the originating message; omitted when the row is not tied to one
source message for per-message token usage; otherwise the usage-event source. Subagent rows keep their real source — they are marked by subagent_session_id, not by a different source
subagent_session_id Id of the subagent session the row came from; omitted for the queried session's own rows
label Display label — Prompt N for message rows, Step N for other rows tied to a message, else the source name
web_search_requests Anthropic server-side web searches this row was billed for, at $0.01 each on top of tokens; omitted when the row performed none
cost Per-row integer microdollar object; includes the web search fee when web_search_requests is present and the row's cost is computed. A row with an authoritative reported cost is assumed to already settle its own server tool use, so the fee is not added on top even when web_search_requests is present. Zero with has_cost: false when the model is unpriced and the row performed no web search; an unpriced computed row that did still reports the fee, because the fee does not depend on token rates

Human output is a compact summary:

Session:       abc-123
Agent:         claude
Output:        15230
Peak ctx:      84000
Subagents:     2 (included)
Cost:          ~$2.41 (claude-opus-4-7)

The Subagents line appears only when the figures cover subagent transcripts, so a session without them (or a --own-only run) prints the same five lines it always has.

The leading ~ on the cost line marks a computed or mixed figure. A reported cost omits it. The parenthesized model list is shown only when contributing models exist, so a cost-only reported session does not render empty parentheses. When some contributing models are unpriced, the cost line reads n/a (unpriced: model-x); when the session has no token data at all, it reads n/a. Priced Copilot-family sessions add an AI Credits line after the cost.

HTTP endpoint — as of 0.32.0, the same data is available over REST:

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

The response uses the same JSON fields shown above and is available from both local SQLite-backed agentsview serve and read-only agentsview pg serve. HTTP responses set server_running: true. As of 0.37.1, pass ?breakdown=true to include the per-step breakdown rows; without it breakdown is [] while breakdown_count still reports the row count. The CLI requests the breakdown on every path (local, --server, and --pg), so its --format json output always includes the rows; it also passes subagents=true unless --own-only was given, so the three backends return the same document. The session detail header uses this endpoint to render its per-step usage breakdown. Existing sessions return 200 OK even when token or cost data is absent; inspect has_token_data, has_cost, and unpriced_models to decide how to present that state. Missing sessions return 404 with:

{
  "error": {
    "code": "session_not_found",
    "message": "session not found"
  }
}

Unexpected usage-query failures return 500 with error.code = "usage_query_failed".

Exit codes — usage keeps the older token-use contract:

Code Meaning
0 Token data or cost present and reported
2 Session not found in the local archive
3 Session exists but has neither token data nor cost

The codes classify the reported document, so a session whose only token data lives in its subagents exits 0, not 3. With --own-only it exits 3, as it did before.

Before querying, the local backend refreshes the session's own transcript and the agent-*.jsonl files under its subagents/ directory, so a session that just finished reports complete numbers. --own-only skips the subagent refresh.

The command uses a writable local daemon when one is running, or starts a detached daemon when fresh local data is needed and no compatible daemon is running. With AGENTSVIEW_NO_DAEMON=1, it falls back to direct local SQLite after acquiring the write-owner lock for any required refresh. Configured PostgreSQL does not change this command's default local behavior; pass --pg to read usage from the shared PostgreSQL store. With --server, it calls GET /api/v1/sessions/{id}/usage on the explicit daemon. With --pg, it reads usage from the shared PostgreSQL store.

Pricing comes from the same model_pricing table and custom pricing overrides that back agentsview usage daily. Replaces the older agentsview token-use, which remains as a deprecated alias.


Activity Report

The Activity report endpoint powers the top-level Activity page and the agentsview activity report CLI command. It returns one resolved range with concurrency buckets, summary totals, breakdowns, and contributing sessions.

GET /api/v1/activity/report
GET /api/v1/activity/report/{report_id}/sessions

Session-page responses omit the complete report by default so browser sorting, bucket filtering, and pagination stay page-bounded. Stateless clients can add include_report=true; a refresh_required response includes its complete replacement report regardless.

Activity includes one-shot sessions by default. Automated sessions are also included by default and can be filtered with the automation query parameter.

The JSON response shares the same schema_version, pricing, and projects metadata contract as agentsview activity report --json.

The report route negotiates its response with Accept. Ordinary clients receive plain JSON. Clients requesting text/event-stream receive throttled progress events followed by one terminal report event. Both forms use the long-running route and are not subject to the ordinary 30-second operation timeout.

Query param Notes
preset day, week, month, or custom
date Anchor date for day/week/month presets (YYYY-MM-DD)
from Custom range start, RFC3339
to Custom range end, RFC3339
timezone IANA timezone name; default UTC
bucket Optional bucket override: 5m, 15m, 1h, 1d, or 1w
project Filter by project
git_branch Filter by opaque branch token from GET /api/v1/branches
agent Filter by agent
machine Filter by machine
automation all, interactive, or automated; default all

Project, branch, agent, and machine filters are limited to 1,024 UTF-8 bytes each and 3,072 bytes combined. The fully encoded signed report ID is also validated before aggregation so JSON escaping cannot overflow the session-page URL token.

Response excerpt:

{
  "schema_version": 7,
  "report_id": "v1.eyJ2IjoxLC4uLn0.signature",
  "sessions_total": 18,
  "sessions_next_cursor": "v1.eyJvZmZzZXQiOjIwMH0.signature",
  "pricing": {
    "source": "fetched",
    "table_version": "litellm-398a0b15378c",
    "latest_row_updated_at": "2026-06-20T18:40:00Z",
    "custom_override_count": 0,
    "effective_row_count": 2432,
    "digest": "sha256:8d815a1737bce68fa1a19ba977bf33c8c8efcc74deb954fcf62ce80e46e75f2c",
    "cost_source": "mixed",
    "fallback": {
      "used": false,
      "models": []
    },
    "models": {
      "gpt-5.4": {
        "cost_source": "computed",
        "resolutions": [
          {
            "priced_model": "gpt-5.4",
            "matched_pattern": "gpt-5.4",
            "input_cost_per_mtok": {"microdollars": 2500000},
            "output_cost_per_mtok": {"microdollars": 15000000},
            "cache_write_cost_per_mtok": {"microdollars": 0},
            "cache_write_1h_cost_per_mtok": {"microdollars": 0},
            "cache_read_cost_per_mtok": {"microdollars": 250000},
            "cost_source": "computed",
            "bands": [
              {
                "above_input_tokens": 272000,
                "input_cost_per_mtok": {"microdollars": 5000000},
                "output_cost_per_mtok": {"microdollars": 22500000},
                "cache_write_cost_per_mtok": {"microdollars": 0},
                "cache_write_1h_cost_per_mtok": {"microdollars": 0},
                "cache_read_cost_per_mtok": {"microdollars": 500000}
              }
            ],
            "application": {
              "base_request_count": 14,
              "aggregate_row_count": 0,
              "bands": [
                {"above_input_tokens": 272000, "request_count": 2}
              ]
            }
          }
        ]
      }
    }
  },
  "projects": {
    "agentsview": {
      "resolution": "resolved",
      "identity": {
        "key": "sha256:97879729c8ab311e9d4b28941e3a04830b28c527f00af53f2270212eccdbbd39",
        "key_source": "git_remote",
        "normalized_remote": "github.com/acme/agentsview"
      }
    }
  },
  "timezone": "America/Chicago",
  "range_start": "2026-06-20T05:00:00Z",
  "range_end": "2026-06-21T05:00:00Z",
  "bucket_unit": "hour",
  "bucket_seconds": 3600,
  "partial": true,
  "as_of": "2026-06-20T18:40:00Z",
  "peak": {"agents": 4, "at": "2026-06-20T15:00:00Z"},
  "totals": {
    "active_minutes": 210.5,
    "agent_minutes": 346.2,
    "sessions": 18,
    "untimed_sessions": 1,
    "distinct_projects": 5,
    "distinct_models": 4,
    "output_tokens": 84231,
    "cost": 12.34,
    "automated_sessions": 3,
    "interactive_sessions": 15
  },
  "buckets": [
    {
      "start": "2026-06-20T15:00:00Z",
      "end": "2026-06-20T16:00:00Z",
      "max_agents": 4,
      "agent_minutes": 52.0,
      "output_tokens": 12000,
      "cost": 1.87,
      "automated_at_peak": 1,
      "interactive_at_peak": 3
    }
  ],
  "by_project": [{"key": "agentsview", "agent_minutes": 96.4, "cost": 4.20}],
  "by_model": [{"key": "claude-sonnet-4-6", "agent_minutes": 80.0, "cost": 3.10}],
  "by_agent": [{"key": "codex", "agent_minutes": 64.0, "cost": 2.85}],
  "by_session": [
    {
      "session_id": "codex:abc",
      "title": "Update docs",
      "project": "agentsview",
      "agent": "codex",
      "primary_model": "gpt-5.4",
      "models": ["gpt-5.4"],
      "agent_minutes": 24.5,
      "cost": 1.12,
      "output_tokens": 9200,
      "first_active": "2026-06-20T15:04:00Z",
      "last_active": "2026-06-20T15:38:00Z",
      "timing_quality": "timed",
      "is_automated": false
    }
  ]
}

Breakdown rows include total, automated, and interactive minutes and costs. Session rows with no reliable timestamped activity use "timing_quality": "untimed" and agent_minutes: null; they can still contribute cost and output tokens when usage rows exist.

Schema v6 returns at most the first 200 session rows in by_session and no longer returns raw activity intervals. Fetch later pages, alternate sorts, or a bucket drill-down through the sessions endpoint. It accepts limit (default 200, maximum 500), cursor, sort, direction, and the zero-based half-open range bucket_start and bucket_end. Both range bounds must be present. If the archive changed since the signed report_id was created, the response sets refresh_required and includes a complete replacement report so clients never combine different report generations.


Secret Scanning

As of 0.30.0, AgentsView scans session content for credentials during sync and exposes findings through CLI, HTTP, and per- session metadata. Two confidence tiers exist:

Tier Rules When scanned
Definite Well-anchored vendor formats: AWS access keys, Anthropic sk-ant-…, OpenAI sk-proj-/sk-svcacct-/sk-admin-, GitHub ghp_… and github_pat_…, GitLab glpat-…, Slack xoxb/xoxa/xoxp/xoxr/xoxs, Stripe sk_live_… and rk_live_…, Google AIza…, npm npm_…, PyPI pypi-…, Hugging Face hf_…, SendGrid SG.…, PEM private-key blocks Inline during sync
Candidate FP-prone heuristics: basic-auth URLs, JWTs, high-entropy assignments Only when agentsview secrets scan runs explicitly

Findings are written to a secret_findings table keyed by session ID, with the rule name, confidence, location (message / tool_input / tool_result / tool_result_event), match coordinates, and a redacted_match value (the raw secret is never stored). Each session also carries a secret_leak_count and a secrets_rules_version so a future ruleset bump can drive an incremental backfill.

HTTP API

GET /api/v1/secrets
POST /api/v1/secrets/scan
GET /api/v1/search/content    (when called with text that matches a secret rule, snippets are masked)

GET /api/v1/secrets accepts: project, agent, date_from, date_to, rule, confidence (definite / candidate / all, default definite), reveal, limit, cursor. reveal=true is only honored on a localhost-bound daemon — remote callers that request reveal receive HTTP 403.

POST /api/v1/secrets/scan streams progress with Server-Sent Events and accepts backfill, project, agent, date_from, and date_to. It is only available from a writable local daemon.

Listing sessions with findings

agentsview session list --has-secret (or has_secret=true on GET /api/v1/sessions) returns only sessions with at least one definite finding. The candidate tier does not contribute to secret_leak_count and so does not surface through this filter.

CLI

The agentsview secrets command group wraps the scan and list operations. The fast path is:

# Re-scan the archive with the full ruleset (definite + candidate)
agentsview secrets scan

# List definite findings (redacted; localhost-only --reveal for raw values)
agentsview secrets list
agentsview secrets list --reveal

PostgreSQL parity

When PostgreSQL sync is enabled, the secret_findings table, the session-level secret_leak_count, and the --has-secret filter all mirror to the shared database. Substring and regex content search work the same way against pg serve, with the same masking and --reveal constraints.

Ingest-time image offload

The normalized Markdown endpoint /api/v1/sessions/{id}/md carries stored tool-result content, including agentsview_image placeholders and image_ref asset references. The HTML export keeps its existing contract. A serving host needs the matching {dataDir}/assets directory. PostgreSQL and CockroachDB retain the reference text but cannot resolve local assets. The raw agentsview session export command streams provider source bytes and retains their original inline payloads.