Core Analysis¶

Project Positioning: agentsview addresses the fragmentation of local AI coding agent sessions, tokens, and cost data across different agents. It solves this by discovering and indexing sessions into a local SQLite (optionally Postgres or DuckDB) database, providing a unified, queryable, and fast aggregated view.

Technical Features¶

• Indexing instead of re-parsing: Sessions are parsed once during sync and written to the DB; subsequent queries use the index (FTS5), avoiding repeated file-parsing and delivering order-of-magnitude faster queries (README mentions >100x).
• Local-first and privacy-focused: Single binary with no account dependency keeps data local for auditability and offline use.
• Cost calculation closer to real usage: Uses LiteLLM pricing with prompt-caching-aware logic to differentiate between naive token sums and actual billing behavior.
• Pluggable backends: SQLite for single-user, Postgres for multi-user/concurrency, DuckDB for read-only mirrors and remote access via Quack.

Practical Recommendations¶

1. Quick local trial: run agentsview serve and ensure agent session directories are mounted or accessible (e.g., ~/.claude/projects).
2. For higher concurrency/multi-user: configure Postgres backend (PG_SERVE=1 and AGENTSVIEW_PG_URL).
3. For read-only distribution/remote analysis: build a DuckDB mirror and expose via Quack or duckdb serve.

Important Notice: agentsview can only discover sessions from directories you explicitly mount or make accessible. In containers, you must mount agent session directories; otherwise agents won’t appear in the UI.

Summary: For local, fast, auditable cross-agent session and cost analysis, agentsview’s indexed approach and cache-aware costing provide a practical and privacy-preserving solution that outperforms tools that re-parse files or depend on cloud accounts.

Core Analysis¶

Key issue: Loopback binding and Host header validation are secure defaults, but you must explicitly configure them for remote access to avoid 403 errors and harden the UI when exposing beyond localhost.

Practical steps (secure remote access)¶

1. Specify the browser-accessible origin: Restart with agentsview serve --public-url https://your-workspace.exe.dev or --public-url http://127.0.0.1:18080. Use --public-origin to trust additional origins.
2. Enable authentication: If exposing the UI beyond loopback, enable --require-auth or place agentsview behind an authenticated reverse proxy.
3. Reverse proxy and TLS: Terminate TLS at Nginx/Traefik and ensure correct Host/header forwarding.
4. Minimize mounts and use read-only: Only mount necessary session directories into containers as read-only, and use named volumes for /data to avoid root-owned host files.
5. Backend choice: For multi-user/production, prefer Postgres (AGENTSVIEW_PG_URL and PG_SERVE=1) to gain better concurrency control, backups, and access management.

Important Notice: Not setting --public-url often causes 403; exposing the UI publicly without authentication or TLS risks data leakage.

Summary: Expose the UI only when needed, explicitly declare trusted origins, enable authentication, protect traffic with TLS and reverse proxy, and use Postgres and strict mount policies for production multi-user scenarios.

Core Analysis¶

Backend selection rationale: agentsview employs a multi-backend strategy to cover needs from single-developer local use to multi-user production and remote analysis. Each backend has trade-offs in operational complexity, concurrency, and analysis suitability.

Technical comparison and strengths¶

• SQLite + FTS5 (default)
• Strengths: Zero-config, single-binary run, ideal for quick local usage; FTS5 provides efficient full-text search for interactive UI/CLI latency needs.

• Use cases: Individual developers, single-machine debugging, quick audits, local use.

• Postgres (PG_SERVE)

• Strengths: Concurrency, user management, robust transactions and backups; better suited for long-term storage and multi-user access.

• Use cases: Team sharing, production deployments, or when SQLite becomes a bottleneck.

• DuckDB + Quack (read-only mirror)

• Strengths: Efficient read-only analytical snapshots for analysis or backups; Quack enables secure remote exposure of the mirror without loading the primary DB.
• Use cases: Offline analytics, read-only distribution, remote BI or auditing.

Practical recommendations¶

1. Use default SQLite for rapid local evaluation: agentsview serve.
2. Move to Postgres with PG_SERVE=1 for multi-user/production reliability.
3. Create a DuckDB mirror and expose via Quack for read-only analysis or remote teams.

Important Notice: SQLite can be a bottleneck under heavy concurrent writes or long-term multi-user scenarios; in containers prefer named volumes to avoid permission issues.

Summary: agentsview balances ease-of-use and scalability: SQLite for quick local use, Postgres for production concurrency, and DuckDB for efficient read-only mirrors and remote analytics.

Core Analysis¶

Suitable scenarios:
- Local-first and privacy-sensitive: Developers or small teams who refuse to upload sessions or rely on cloud accounts.
- Cross-agent unified search & debugging: When you use Claude, Forge, Codex, etc., and want a single view for sessions and search.
- Local cost-aware ops: Quickly estimate tokens/model costs locally and perform daily monitoring (offline/auditable).

Not suitable or limited scenarios:
- Automatic collection of cloud sessions: agentsview can only index local/mounted directories and cannot auto-collect cloud-hosted sessions.
- Very large-scale or high-concurrency multi-user deployments: SQLite may become a bottleneck; migrate to Postgres with operational overhead.
- New/non-standard agent formats: Requires writing parsers to index nonstandard session formats.

Trade-offs vs alternatives¶

• Cloud billing dashboards / centralized logging: Better for cross-machine/organization billing accuracy and compliance, but sacrifices local privacy and requires accounts/network.
• Self-hosted log aggregation (ELK/ClickHouse): Good for massive long-term retention and complex analytics, but costly to operate.
• agentsview strength: Fast local onboarding, indexed queries, cache-aware cost estimation, no account dependency.

Recommendation: Use agentsview as your local debugging and local-cost-visibility tool. For cross-machine centralized billing or enterprise auditing, integrate agentsview’s DuckDB mirror or Postgres backend with your centralized logging/billing stack to balance local readability with centralized governance.

Summary: agentsview excels for local visualization, privacy, and quick searches; for scale or cloud-oriented needs, pair it with Postgres or enterprise log systems.

Core Analysis¶

Key issue: Simply summing tokens in session logs often misrepresents actual billing due to prompt caching, context reuse, and model-specific pricing. agentsview combines model pricing with cache-aware logic to produce local estimates that better approximate real billing.

Technical implementation analysis¶

• Pricing source: Uses LiteLLM pricing by default and offers offline fallbacks to estimate costs when online pricing is unavailable.
• Cache-aware logic: During cost calculation, agentsview identifies prompts or segments that were not actually sent to the model (e.g., satisfied by a local prompt cache or re-used context) and excludes them from token billing totals to avoid double-counting.
• Dependence factors: Accuracy depends on session logs containing sufficient token metadata (model used, per-request token details) and on the pricing table covering the models in use.

Practical recommendations¶

1. Ensure detailed session logs: Have agents or your environment preserve token granularity and model identifiers so agentsview can map usage to pricing items.
2. Validate pricing data: If using new models or custom pricing, configure offline fallback or custom pricing to avoid missing rates.
3. Treat the dashboard as a near-real operational view: For exact accounting, rely on provider invoices, but use agentsview to get realistic local consumption insights.

Important Notice: If sessions lack token detail or a model isn’t priced, cost fields may be missing or inaccurate; provide pricing info or increase log detail in that case.

Summary: The prompt-caching-aware approach reduces false overestimates by excluding cache-hit usage from billed totals, improving local cost visibility—provided session metadata and pricing data are adequate.

Core Analysis¶

Key issue: agentsview depends on parsers to map different agent session files into a unified DB schema. To support a new agent, you must implement a parser that provides the required data for indexing and cost computation.

Extension steps (general flow)¶

1. Analyze session format: Locate the agent’s session root and understand file layout and message structure (requests/responses, timestamps, model IDs, token details).
2. Define mapping to internal schema: Decide how to map messages into agentsview’s session/event/message model, ensuring you capture model IDs and per-event token counts or raw text for tokenization.
3. Implement parser logic: Add a parsing module to discover, read, parse, transform, and write data into the DB; handle incomplete sessions and partial metadata.
4. Integrate discovery: Register the parser with agentsview’s discovery process so the agent is indexed on sync.
5. Test and validate: Run a full sync, confirm sessions appear in UI/CLI, and verify search, session browsing, and cost fields.

Complexity and caveats¶

• Complexity: Moderate; depends on format complexity and whether token/model granularity exists. JSON/text is easier; binary/mixed formats are harder.
• Key caveat: Ensure parser produces model identifiers and token counts (or raw text suitable for tokenization) or cost calculations will be limited.

Important Notice: If token details aren’t available, you can still index transcripts for search but cost fields may be missing or only roughly estimated.

Summary: Adding a parser for a new agent is a routine engineering task. The essential work is mapping source sessions to a unified schema that supports indexing and cost computation.