DOCSEARCHbyAlgolia
Submit Docs

agentsview

repository·main·Indexed 25 days ago

https://github.com/kenn-io/agentsview

A local-first tool for browsing, searching, and tracking costs across various AI coding agents. It provides a web UI and CLI to analyze session data, token usage, and compute costs without requiring external accounts. It includes an experimental Tauri-based desktop wrapper and supports multiple backends including SQLite, DuckDB, and PostgreSQL.

Tokens
112.1K
Snippets
195
Records
522
Agent score
88%

What's inside agentsview

  1. Overview of AgentsView

    main
    AgentsView is a local-first desktop and web application designed for browsing, searching, and analyzing past AI coding sessions. It allows developers to track usage, costs, and time spent across various projects, models, and tools. It automatically discovers sessions from dozens of supported AI agents without requiring manual configuration.

  2. Overview of Recall (Experimental)

    main

    Recall is an experimental layer for managing durable, provenance-linked knowledge from past agent sessions. Unlike semantic search (which finds passages in transcripts), Recall searches a distilled set of compact facts, procedures, preferences, and warnings.

    Key Characteristics:

    • Storage: Currently local and SQLite-only. Not available for PostgreSQL or DuckDB stores.
    • Retrieval: Supports lexical (default), vector, and hybrid retrieval.
    • Provenance: Every entry is linked to a source session with mechanical evidence verification (message ordinals, tool uses, etc.).
    • Trust Model: Entries exist in different review states (e.g., human_reviewed, unreviewed_auto). Only human_reviewed entries are considered trusted for trusted-only reads.

    !!! warning "Active research" Recall's schema, scoring, and workflows are subject to change. Upgrades may require rebuilding tables. The session archive is the source of truth and must not be deleted or recreated to reset Recall.

  3. Understand Artifact Export Reliability Design

    main

    The Artifact Export Reliability design addresses consistency gaps in the publication ledger. It ensures that artifact exports are bounded in memory, validated against the correct origin, and handle deterministic failures without blocking the entire export queue.

    Key improvements include:

    • Origin Validation: Prevents stale exporters from publishing under incorrect namespaces by verifying the artifact_origin_id within the same transaction as the mutation.
    • Bounded Session Loading: Prevents memory exhaustion by using a transactional bounded loader that stops reading once specific cardinality or byte budgets are exceeded.
    • Durable Rejection State: Allows deterministic failures (like size limit violations) to be recorded as 'rejected' outcomes in the artifact_export_queue, allowing other successful claims in the same batch to proceed.
    • Automatic Retries: Content mutations automatically advance the queue generation, which clears previous rejection states and triggers a retry.

  4. Understand Session Intelligence signals

    main

    AgentsView (v0.23.0+) provides a session-intelligence layer that computes health signals, outcome classifications, and aggregate analytics for agent sessions. These signals are heuristics used for triage and pattern-finding.

    Health Score

    A penalty-based score out of 100, mapped to grades:

    • A: 90-100
    • B: 75-89
    • C: 60-74
    • D: 40-59
    • F: 0-39

    Outcome Classification

    Sessions are classified into one of four outcomes with a confidence level (high, medium, or low):

    • completed
    • abandoned
    • errored
    • unknown

    Key Signal Categories

    • Tool-Health: Tracks tool failures, retries (3+ identical calls), edit churn (3+ edits to a file in a tight window), and consecutive failure streaks.
    • Context Signals: Tracks compaction counts, mid-task compactions (interrupting active work), and maximum context pressure.

  5. Understand the Microdollar Money Representation

    main

    AgentsView uses a fixed-precision integer representation for all monetary values to avoid floating-point errors. All money is represented as signed 64-bit microdollars, where 1 USD = 1,000,000 microdollars.

    Key constraints:

    • One microdollar is $0.000001 (one ten-thousandth of a cent).
    • The range covers approximately ±$9.22 trillion.
    • All public machine-readable JSON outputs must use the Money object format.
    • Human-facing interfaces (CLI/UI) render these as standard dollar strings (e.g., $0.42).
    {
  "microdollars": 420000
}

  6. Understand imported data content and appearance

    main

    When you import conversations, AgentsView processes the following data:

    Messages

    All conversation turns are imported as sessions, including user messages, assistant responses, thinking/reasoning blocks, and tool usage (e.g., code interpreter, web search, DALL-E).

    Images (ChatGPT only)

    AgentsView extracts DALL-E generations and uploaded files from the ChatGPT .zip and stores them in the local data assets directory. Supported formats include PNG, JPG, JPEG, WebP, and GIF. Images are displayed inline in the message viewer.

    Metadata

    Each session includes:

    • Conversation title (used as the session display name)
    • Created and updated timestamps
    • Message and user message counts
    • Model information (where available)

    Organization and Features

    • Grouping: Imported sessions are grouped under the claude.ai or chatgpt.com project. You can use the project filter to find them.
    • Functionality: Imported sessions support all standard AgentsView features, including search, export, publish to Gist, insights, pinned messages, and analytics.

  7. Understand PostgreSQL Semantic Search Replication

    main

    The internal/postgres package implements a db.VectorSearcher seam over pgvector, acting as a passive replica of the local vectors.db.

    Key behaviors:

    • No Server-Side Computation: Embeddings are never computed on the PostgreSQL server; they are computed locally and pushed.
    • Data Sync: The pg push command copies the active generation's documents and chunks to the database.
    • Parity: It reuses fusion machinery (RRFMerge, unit fusion keys, subordinate penalty, snippet construction) from internal/db to ensure semantic/hybrid search parity between local SQLite and remote PostgreSQL backends.

  8. Analyze session costs and analytics in the Web UI

    main

    The AgentsView Web UI provides several dashboards for monitoring agent activity and expenses:

    • Token usage and cost dashboard: View per-session and per-model cost breakdowns, along with daily spend charts.
    • Analytics dashboard: Access activity heatmaps, tool usage metrics, velocity metrics, and project breakdowns.
    • Recent Edits feed: Track files changed by agents across all sessions, grouped by project and path. Each entry links directly to the message that triggered the change.
    • Live updates: The UI uses Server-Sent Events (SSE) to provide real-time updates as active sessions receive new messages.

  9. Understand the Semantic Search storage layout

    main

    Semantic search data is stored in a separate SQLite database named vectors.db, located alongside the main sessions.db archive.

    Key characteristics:

    • Resilience: vectors.db is not affected by a parser-change resync of sessions.db. A resync rebuilds sessions.db atomically, and the next mirror refresh re-derives identities, ensuring unchanged documents keep their vectors.
    • Self-contained: The mirror copies message content into vectors.db so it can serve queries without needing the main archive open.
    • Disposable: vectors.db can be deleted and rebuilt using embeddings build --full-rebuild without impacting sessions.db.

  10. Quickstart: Semantic Search with Ollama

    main

    To use Ollama for semantic search, pull an embedding model and point agentsview to Ollama's OpenAI-compatible /v1 endpoint.

    1. Pull the model:
    ollama pull nomic-embed-text
    1. Configure ~/.agentsview/config.toml:
    [vector]
enabled = true

[vector.embeddings]
model = "nomic-embed-text"
dimension = 768

[vector.embeddings.servers.local]
endpoint = "http://localhost:11434/v1"

  11. Quickstart: Ollama Embeddings

    main

    Ollama provides an OpenAI-compatible endpoint for embeddings at /v1.

    1. Pull an embedding model in Ollama.
    2. Ollama serves the endpoint at /v1 with no API key required.
    3. The agentsview /v1/embeddings route passes the dimensions field through to Ollama, allowing for Matryoshka reduction if supported.

  12. Push Embeddings to PostgreSQL

    main

    If using PostgreSQL as a backend, agentsview pg push copies the active generation from the local vectors.db mirror into PostgreSQL using halfvec chunk tables.

    • Incremental Push: By default, only the active generation and sessions with changed document sets are pushed.
    • Full Push: Use pg push --full to bypass change detection and re-send all session vectors.
    • Disable Vector Push: To skip the vector phase during a push, use --no-vectors or set push_vectors = false in the [pg] config section.

    Note: A machine with [vector] enabled will attempt to push embeddings automatically during the push phase.