vylor-savings-estimator

Instantly estimate how much Vylor MCP cuts costs and tokens on your Claude AI sessions — zero configuration required.

Reads your Claude session .jsonl files (Claude Code CLI & Claude Desktop), detects file-exploration and repo-crawling patterns that Vylor MCP replaces, and produces a rich savings report tracking cost cut and tokens cut.

Key Features

• Automatic Session Discovery: Automatically discovers sessions from default Claude Code CLI (~/.claude/projects/) and Claude Desktop directories across Windows, macOS, and Linux.
• Automatic Sub-Agent Stitching: Detects background sub-agents (e.g. Explore agents spawned via the Agent tool) and stitches them into their root task session, reporting true total task cost and sub-agent turn counts.
• Direct File-Cache Compounding Model: Accurately models the prompt cache "snowball effect"—avoiding file dumps on early turns eliminates re-reading those files from the prompt cache on every subsequent turn.
• Rich Terminal Report: Beautiful, modern terminal dashboards powered by rich with full savings breakdowns by tool, model, and session.
• Extensible OOP Architecture: Built with SOLID principles, abstract interfaces (ISessionDiscoverer, ISessionParser, ITurnClassifier, ISavingsEngine, IReportRenderer), and Dependency Injection.

Installation

From Source / Private Repository

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

Once Published to PyPI

pip install vylor-savings-estimator
# or via pipx (isolated environment)
pipx install vylor-savings-estimator

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/

How Savings Are Calculated

The Compounding Cache Reality

In Claude Code and Claude Desktop, reading files writes their contents directly into the prompt cache (cache_creation_input_tokens). On every single subsequent turn for the rest of the session—even when the model is merely editing code or reasoning—those files are repeatedly re-read from the cache (cache_read_input_tokens).

The Direct File-Cache Model

1. 100% Avoided Context: The actual tokens loaded by file exploration (Read, read_file, list_dir, grep) are eliminated from entering the context.
2. Downstream Cache Reduction: That avoided volume is subtracted from cache_read_tokens on every future turn in the session: $$\text{saved_cache_read} = \min(\text{turn.cache_read_tokens}, \text{accumulated_avoided_context})$$
3. 0% Output Tokens: The model still writes all its code, plans, and answers—output tokens are never credited as saved.

What It Detects

Example Output

Found 2 session file(s). Parsing...

                            VYLOR SAVINGS ESTIMATE                             
               Analyzed: 1 session(s)  |  29 turns  |  All-time                
                         (includes 12 sub-agent turns)                         

+-----------------------------------------------------------------------------+
| Metric              |  Baseline (paid) | With Vylor MCP |    Saved |  % Cut |
|---------------------+------------------+----------------+----------+--------|
| Total Cost          |          $0.5565 |        $0.3080 | -$0.2485 | -44.7% |
| Total Tokens        |            1.03M |         377.1K |  -656.0K | -63.5% |
+-----------------------------------------------------------------------------+

--------------------------- Top Sessions by Savings ---------------------------
+-----------------------------------------------------------------------------+
| Session ID              | Turns | Baseline Cost | Cost Saved |  % Cut | Sub-agents |
|-------------------------+-------+---------------+------------+--------+------------|
| 4bc32054-f243-42...e29f |    29 |       $0.5565 |   -$0.2485 | -44.7% |         12 |
+-----------------------------------------------------------------------------+

+-----------------------------------------------------------------------------+
| Powered by Vylor MCP -- https://github.com/vylor-ai/vylor-mcp               |
+-----------------------------------------------------------------------------+

Session File Locations

Automatically discovered from platform defaults:

Development

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