vylor-savings-estimator

See how much your Claude AI sessions waste on file exploration — in tokens, cost, and time. Zero configuration.

Reads your Claude session .jsonl files (Claude Code CLI & Claude Desktop), detects the file-exploration and repo-crawling patterns that Vylor MCP replaces, and reports how much of your spend was avoidable waste.

Install

One command (standalone binary, no Python needed)

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/Vylor-AI/vylor-saving-estimator/main/install.sh | sh

Windows (PowerShell)

irm https://raw.githubusercontent.com/Vylor-AI/vylor-saving-estimator/main/install.ps1 | iex

Or download the binary for your platform from Releases:

Manual install on macOS / Linux:

chmod +x vylor-estimate-macos
mv vylor-estimate-macos /usr/local/bin/vylor-estimate

On Windows, move vylor-estimate.exe to any folder in your PATH.

From source

git clone https://github.com/vylor-ai/vylor-saving-estimator.git
cd vylor-saving-estimator
pip install -e .

Via pip / pipx (Python 3.10+)

pip install vylor-estimate
# or in an isolated environment
pipx install vylor-estimate

Usage

# Auto-discover all Claude sessions (defaults to last 30 days)
vylor-estimate

# Date filtering
vylor-estimate --week          # last 7 days only
vylor-estimate --month         # last 30 days only
vylor-estimate --all           # all-time (disable default 30-day filter)
vylor-estimate --since 2025-09-01

# Explicit path (single file or custom directory)
vylor-estimate /path/to/session.jsonl
vylor-estimate /path/to/sessions/

# Detailed report (waste by source, model, and session)
vylor-estimate -d

Session files are read locally. No data is sent anywhere.

Example Output

Default: one table, one hint.

                              AGENT OVERHEAD ESTIMATE
                      Analyzed: 5 session(s)  |  Last 30 days

     +--------------------------------------------------------------------+
     |                     |            Cost |        Tokens |       Time |
     |---------------------+-----------------+---------------+------------|
     | Total               |         $2.6576 |         6.14M |        11m |
     | Avoidable overhead  | $2.2445 (84.5%) | 5.39M (87.8%) | 9m (83.2%) |
     +--------------------------------------------------------------------+
                      Top overhead sources: sub-agents 98%
                            Run with -d for details.

• Total is what the analyzed sessions cost, in cost, tokens and time.
• Avoidable overhead is the portion spent on exploration and reconnaissance that Vylor tools make unnecessary.
• Top overhead sources tells you what contributes most to the overhead.

-d adds overhead by source (cost, tokens, time), a breakdown by model, and the top sessions by overhead.

How Overhead Is Estimated

A turn counts as avoidable overhead when it is one of:

Rules for main-agent turns:

• Pure exploration only. Every tool call in the turn must be exploration. A turn that also edits files, builds, or runs tests is not counted.
• Shell commands are inspected. Bash / PowerShell count only when the command is exploration (cd src && grep -rn foo . | head). git commit, npm test or git log | grep fix do not.
• For an overhead main-agent turn, the output tokens and the prompt-cache reads it caused are counted. For a sub-agent turn, everything is counted.

Avoidable time

Time is agent-time: the sum of the durations of overhead turns, using the turn timestamps in the session files. It is model generation time only (not tool run time), each turn is capped at 10 minutes so idle gaps don't skew the totals, and parallel sub-agents can overlap, so it can exceed the wall-clock time.

The compounding cache

Reading files writes their contents into the prompt cache. On every later turn of the session those files are re-read from the cache, so avoided exploration also shrinks the cache reads of later turns. That is why exploration is more expensive than its own token count suggests.

Session File Locations

Automatically discovered from platform defaults:

Development

git clone https://github.com/vylor-ai/vylor-saving-estimator.git
cd vylor-saving-estimator
pip install -e ".[dev]"
pytest

Binaries are built by build-binary.yml on every v* tag and published to this repo's Releases.