Advanced Guide

Power-user workflows: model distribution analysis, cross-project benchmarking, the web dashboard, JSON output for scripting, and contributing to AgentSight.

Model Distribution with --by-model

If your workflow uses multiple models (Opus, Sonnet, Haiku), the --by-model flag on summary breaks down usage per model:

$ agentsight summary --by-model --days 30

 ── Last 30 Days ─────────────────────────────────────
 Sessions:            52
 Total tokens:        18,421,003

 ── Cost by Model ────────────────────────────────────
 claude-opus-4-6:     $68.12  (81.7%)
 claude-sonnet-4-6:   $15.29  (18.3%)

Use --group-family to merge dated model variants (e.g., collapse claude-sonnet-4-6 and claude-3-5-sonnet-20241022 into one line):

$ agentsight summary --by-model --group-family

This helps you understand whether your token budget is going to the right models. Opus is more capable but costs more; if most sessions are routine, Sonnet might be a better default.

Cross-Project Benchmarking

Use the --project flag on diagnose to compare efficiency across projects:

$ agentsight diagnose --project work/api --days 30
$ agentsight diagnose --project personal/tools --days 30

Compare cache hit ratios, retry patterns, and tool distributions. Projects with a well-maintained CLAUDE.md will consistently show better numbers. Use --with-context to include CLAUDE.md analysis in the diagnose output:

$ agentsight diagnose --project work/api --with-context

The Web Dashboard

For a richer visual experience, launch the built-in web dashboard:

$ agentsight dashboard

This opens http://127.0.0.1:3141 in your browser with:

Dashboard flags:

agentsight dashboard --port 8080    # Custom port
agentsight dashboard --no-open      # Don't auto-open browser
agentsight dashboard --replace      # Replace a running instance

JSON Output for Scripting

Every command supports --json for machine-readable output:

$ agentsight --json sessions --days 7 | jq '.[0].cache_hit_ratio'
0.706

$ agentsight --json diagnose | jq '.tool_patterns.bash_loops'
[]

$ agentsight --json summary --by-model | jq '.models'

Use this to build custom dashboards, Slack alerts, or CI checks. For example, a post-session hook that warns if cache efficiency drops below a threshold:

#!/bin/bash
ratio=$(agentsight --json diagnose | jq '.cache_hit_ratio')
if (( $(echo "$ratio < 0.5" | bc -l) )); then
  echo "Warning: cache hit ratio is ${ratio} — consider reviewing CLAUDE.md"
fi

Cost Estimation

For pay-per-token API users, add --cost to any command to see dollar amounts:

$ agentsight --cost session abc123

 ── Token Breakdown ────────────────────────────────
 Category         Tokens      Cost
 Input            65,500      $0.33
 Cache creation    9,600      $0.29
 Cache read       65,000      $0.20
 Output            1,040      $0.08
 ─────────────────────────────────────────────────
 Total           141,140      $0.90

To make cost display the default, set billing = "api" in your config:

# ~/.agentsight/config.toml
billing = "api"

Config File Customization

AgentSight reads its configuration from ~/.agentsight/config.toml, which is created automatically on first run. You can customize model pricing for custom or fine-tuned models:

# ~/.agentsight/config.toml

# billing = "api"

[models."claude-opus-4-6"]
input_per_million = 5.00
output_per_million = 25.00
cache_creation_per_million = 6.25
cache_read_per_million = 0.50

Built-in pricing covers all standard Claude models. Only add overrides if you need custom values.

Environment Health Check

The health command verifies your setup and provides a baseline usage report:

$ agentsight health

 ── Environment ────────────────────────────────────
 Claude dir:  ~/.claude  (found)
 Sessions:    47 sessions across 8 projects
 Config:      ~/.agentsight/config.toml (default)

 ── Baseline Usage ─────────────────────────────────
 Last 7 days:  2.1M tokens across 12 sessions
 Avg cache hit ratio: 71.3%
 Most active project: work/api (8 sessions)

Use --quick for just the environment audit, or --project to scope the baseline to a specific project.

Contributing

AgentSight is open source and welcomes contributions. The codebase is Rust, built with:

To get started:

git clone https://github.com/RealNerd/agentsight.git
cd agentsight
cargo test
cargo run -- health

The test suite includes sanitized session fixtures covering normal usage, bash-heavy sessions, cache churning, error retries, multi-model sessions, and edge cases. All 110+ tests pass on every commit.

github.com/RealNerd/agentsight