AgentsView can put coding-agent session logs from several tools into one searchable local archive. This guide is for an engineering lead who needs to find one known task, inspect the usage fields its agent actually recorded, and identify the source of any cost figure.

This is a documentation-based walkthrough of AgentsView's October 9, 2026 v0.45.0 release and current quick-start and token-usage guides, checked October 17. BIG CHANGE has not installed AgentsView, imported a transcript, or tested these steps. Check the version you install, since documentation and release listings can change.

Before you begin

You need a completed coding-agent session you are allowed to read, a distinctive phrase or session ID from that task, and permission to read its local log directory. The Quick Start lists desktop downloads for macOS, Windows and Linux, with CLI wheels for Linux x86_64 and aarch64, macOS x86_64 and arm64, and Windows x86_64 and arm64. The desktop app is bundled; a source build has separate Go, Node and CGO requirements. Basic local archiving does not call for a hosted account or an API key in the quick start.

Session logs may contain prompts, source code, tool inputs and secrets. Choose only directories your team permits you to inspect. Decide which providers and roots the archive may ingest before its first startup: a bare agentsview serve discovers and syncs default supported sources immediately. Keep the web UI on its documented loopback address for this exercise. Do not turn on hosted raw sync, PostgreSQL or ClickHouse pushes, Gist publishing, generated insights, or a hosted embedding endpoint just to answer this question. Semantic search is optional; ordinary full-text search works with the local index.

1. Install and identify the binary

Choose one method in the installation guide. For a standalone CLI, its documented permanent Python install is:

Terminal
pip install agentsview
agentsview --version

The guide also offers uvx agentsview for running without a permanent install, platform installers and desktop packages. On macOS, the Homebrew cask links the app's bundled CLI; an app installed from a DMG may need its CLI directory added to PATH. Confirm which executable your shell finds before trusting its version. GitHub labels v0.45.0 as its October 9 release, but use your own --version result when interpreting the screens and report schema.

2. Restrict sources before the first sync

For a host CLI or desktop installation, set up a fresh data directory and its config.toml before starting AgentsView. The configuration guide documents disabled_agents for excluding local filesystem providers and [agents.<id>].dirs for replacing one provider's default roots. List every other provider ID from that guide's Session Discovery table in disabled_agents, and set the one authorized provider's dirs to the approved root. For example, [agents.codex] with dirs = ["/approved/codex/sessions"] replaces Codex's default directories; adjust the path for your system. If you do not have a complete exclusion list, do not start the host daemon yet. A single CODEX_SESSIONS_DIR or CLAUDE_PROJECTS_DIR override changes that provider's root but leaves other providers eligible for their own default discovery.

Use a fresh AGENTSVIEW_DATA_DIR for this audit if an existing archive may already contain unrelated sessions. The configuration guide says disabled providers' previously archived sessions remain available, so changing the setting does not purge an old archive. It also says disabled_agents covers local discovery and watching, not remote imports or exports; leave remote hosts and export destinations unconfigured for this local task.

An isolated container is the alternative when maintaining an all-other-providers exclusion list is impractical. The Quick Start Docker example publishes the UI only on 127.0.0.1, mounts an agent source read-only and uses a separate data volume. Mount only the authorized source root and set its matching directory variable inside a fresh container; omit the other mounts in the project's Compose example. A container sees only explicitly mounted host session directories. The published Docker images cover Linux amd64 and arm64; this path needs a working Docker installation.

3. Build the local archive

For the scoped host CLI, start the documented foreground server:

Terminal
agentsview serve

After you have applied and checked the source scope in step 2, this initializes ~/.agentsview/sessions.db (or the chosen data directory), discovers enabled agent logs, syncs them, watches for changes and opens http://127.0.0.1:8080. Leave that terminal open. If you prefer a background process, use agentsview daemon start and agentsview daemon status; the desktop app manages its own backend. A compatible server already running may simply report its URL, so check for a running daemon before assuming your new configuration governed ingestion.

If you chose the isolated container, start it with the documented Docker command after checking its single read-only source mount and fresh data volume. Use its loopback UI and run the later agentsview CLI reports inside that container so they read the same archive. Do not run an unscoped host serve alongside it.

Check that the known task's source appears and that unintended providers do not. If the session is missing, inspect the approved path, provider setting and sync status before concluding that no session exists. Run agentsview sync when you need newly changed files committed before a report; the server also watches for changes. Recheck the configured scope before any full resync.

4. Find the task and verify the transcript

In the web UI, use Ctrl/Cmd+K to search for a distinctive literal phrase from the known task. Narrow the list by project, agent or date, then open the candidate and check its messages and tool calls. If you already have the full session ID or UUID, Ctrl/Cmd+G opens it directly. These controls are documented in the Quick Start. Record the agent, session ID and date so you can connect the usage result to the right conversation.

If literal search misses the task, try a shorter phrase and confirm that the underlying agent wrote a local transcript to a directory AgentsView can read. A task present only in a remote service, an unsupported format, or a directory outside the configured roots cannot be recovered by searching harder. Do not enable semantic indexing or transcript upload as a routine fix for a missing local source.

5. Inspect the session's usage fields

Open the matched session's usage view and identify the recorded model, input, output, cache creation and cache read fields that are present. The token-usage guide labels cost reporting experimental and still maturing. AgentsView ingests model and token metadata from source logs and retains raw token usage on message rows. It uses explicit costs reported by a source when available; otherwise it computes a cost from usable tokens and model rates. Its JSON provenance calls these reported, computed or mixed.

If you want a saved machine-readable record for that one session, the project's CLI example uses agentsview session usage SESSION_ID --format json. Replace SESSION_ID with the ID you verified in the transcript, then retain the JSON with your task note. Check the reported model, token buckets and cost source in that output before quoting any total.

Treat a blank field or missing model as unknown. AgentsView cannot reconstruct usage that the agent never wrote. Its release notes say Junie CLI ingestion excludes IDE-only conversations and tool calls, while Antigravity plaintext fallback has transcript content without token usage or cost. Those are concrete examples of why a searchable session need not have a complete spend figure. A reported source amount can also describe a session total while per-model allocations remain estimates.

6. Bound the day report

Use the Usage page's date, project and agent filters to inspect the day containing the session. The page also offers a Top Sessions by Cost table that links back to individual transcripts. For an auditable terminal report, substitute the session's local date and agent name in:

Terminal
agentsview usage daily --since YYYY-MM-DD --until YYYY-MM-DD --agent codex --breakdown

The daily table separates uncached input, output, cache creation and cache reads, with per-model rows when --breakdown is set. The date is bucketed in the system time zone unless --timezone is supplied. A day total can include other sessions from that agent; it is a check on scope and magnitude, not the cost of the one task. Keep the session ID alongside the day report and check which rows actually belong to it.

For a report without a pricing-catalog fetch, add --offline. AgentsView says this reads the existing archive without source sync or daemon startup and uses its embedded price fallback. Refresh the archive first if recent session changes matter; an offline report cannot discover new logs. Normal usage commands may fetch LiteLLM and OpenRouter pricing, while the embedded catalog ages with the installed release.

7. Interpret the number and stop the service

Label each figure according to its provenance. Computed means AgentsView multiplied logged tokens by selected rates. Reported means the source supplied an explicit cost. Mixed means the report combines kinds. Even a source-reported figure is not proof that a provider invoice for the whole account has been reconciled. Compare the relevant provider's own billing or plan records independently, particularly when service tiers, discounts or subscription allowances matter. AgentsView's documentation says it cannot infer Batch, Flex, Priority, regional or one-hour cache pricing when the stored usage omits that tier. Some tool-side tokens are absent from local transcripts.

Your success check is a matched transcript whose agent, ID and date agree with the selected usage view, with available model and token fields recorded and any unavailable fields marked unknown. The resulting artifact is a local searchable archive and a bounded task/day usage note, not an invoice. Stop a foreground agentsview serve with Ctrl+C, or stop a background server with agentsview daemon stop. The Quick Start says stopping the daemon stops both the web UI and session watcher.

The big change

A local transcript gives the cost discussion a traceable starting point. The engineering lead can follow a number back to a specific recorded task and see whether it came from the agent or from a price catalog. Where the log is incomplete, the report should preserve that gap.

Sources & further reading