Metadata-Version: 2.4
Name: vylor-estimate
Version: 0.1.0
Summary: Estimate how much Vylor MCP would save on your Claude AI sessions
Author: Vylor AI
License-Expression: MIT
Project-URL: Homepage, https://vylor.ai
Project-URL: Repository, https://github.com/Vylor-AI/vylor-saving-estimator
Project-URL: Bug Tracker, https://github.com/Vylor-AI/vylor-saving-estimator/issues
Project-URL: Changelog, https://github.com/Vylor-AI/vylor-saving-estimator/releases
Keywords: claude,mcp,vylor,cost,tokens,savings,ai,anthropic
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Utilities
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=13.0
Requires-Dist: click>=8.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Dynamic: license-file

# vylor-savings-estimator

> **Instantly estimate how much [Vylor MCP](https://github.com/vylor-ai/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

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

### Once Published to PyPI

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

---

## Usage

```bash
# 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
 
| Vylor Tool | Replaces | Supported Tools & Patterns |
|---|---|---|
| `find_files` | Heavy file reads & dumps | `Read`, `read_file`, `cat`, `view_file`, sequential multi-reads |
| `request_repo_map` | Directory exploration & trees | `Glob`, `list_dir`, `ls`, `tree`, `find` |
| `find_code_definition` | Symbol searching & code crawling | `Grep`, `grep_search`, `ripgrep`, regex scans |

> [!NOTE]
> Sessions that already use Vylor MCP tools (`mcp__vylor__*`, `request_repo_map`, etc.) are detected and skipped automatically to prevent double-counting or estimating phantom savings on already optimized runs.

---

## 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:

| OS | Search Locations |
|---|---|
| **Windows** | `~/.claude/projects/` (Claude Code CLI)<br>`%APPDATA%\Claude\projects\` (Claude Desktop) |
| **macOS** | `~/.claude/projects/`<br>`~/Library/Application Support/Claude/projects/` |
| **Linux** | `~/.claude/projects/`<br>`~/.config/Claude/projects/` |

---

## Development

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