Metadata-Version: 2.4
Name: ccexplorer
Version: 0.0.1
Summary: Local-first Cost Explorer for Claude Code sessions -- slice your spend by tool, project, session, model
Project-URL: Homepage, https://github.com/mbailey/ccexplorer
Project-URL: Repository, https://github.com/mbailey/ccexplorer
Project-URL: Issues, https://github.com/mbailey/ccexplorer/issues
Author: Mike Bailey
License: MIT License
        
        Copyright (c) 2026 Mike Bailey
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: ccusage,claude,claude-code,cost,observability,tokens
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# ccexplorer

**Local-first Cost Explorer for Claude Code sessions.** Walks
`~/.claude/projects/<project>/<session>.jsonl`, aggregates token usage,
and renders an AWS-Cost-Explorer-style interactive HTML report so you
can slice your spend by **tool, project, session, model, and time**.

> **Status: alpha** -- v0.0.1 ships the `cce build` static-HTML path.
> CLI query subcommands (`get-cost-and-usage`, `get-dimension-values`)
> and the Trusted-Advisor-style recommendations engine are next.

## Why

ccusage already does cost calculation well. ccexplorer adds two things
the existing tools don't:

1. **Tool/agent attribution.** Apportions each assistant turn's cost
   across its `tool_use` blocks so you can see *which tools* the money
   actually went to (and how much went to non-tool conversation).
2. **A slice-and-dice surface.** Same query model as AWS Cost
   Explorer -- time-period x granularity x metrics x group-by x filter
   -- so you can answer questions like "today's voicemode tool calls,
   grouped by session" without writing SQL.

A recommendations engine ("Trusted Advisor for Claude Code") is the
next layer on top -- top-N tool over-use, repeat-read detection,
cache-write premium, etc.

## Privacy

100% local. The tool never makes a network call. The report is a
single HTML file with your data embedded as JSON; it loads
[Chart.js](https://www.chartjs.org/) from a CDN but nothing else
leaves your machine.

## Install

```bash
# Zero-install run
uvx ccexplorer

# Or install persistently
pip install ccexplorer
```

## Usage

```bash
# Walk ~/.claude/projects, build /tmp/cce.html, open it in your browser
cce build

# Custom output path, no browser launch
cce build --output ~/cce-report.html --no-open

# Different projects root (rarely needed)
cce build --projects-root /path/to/.claude/projects
```

Run with no subcommand and you get `cce build` with default flags --
the "just show me the pretty thing" path.

## What the report shows

* Total spend, with breakdowns by tool, project, session, model, and day
* Tool vs non-tool token-cost split (often surprising -- ~50% of long
  sessions is non-tool conversation)
* Cache-write / cache-read / input / output split (cache writes are
  often the largest line item on Opus sessions)
* AWS-Cost-Explorer-style sidebar: time-range presets (1d / 7d / 30d /
  All), group-by dropdowns, filter chips, advanced toggles

## Roadmap

* [ ] `cce get-cost-and-usage` (CLI flagship, mirrors `aws ce`)
* [ ] `cce get-dimension-values` (enumerate tools / projects / models)
* [ ] AGENT dimension (extract sub-agent type from `Agent` tool calls)
* [ ] TAG support (sidecar `<session>.tags.json` or `cce tag` command)
* [ ] COST_CATEGORY rules engine
* [ ] `cce serve` (live local server, no rebuild on every change)
* [ ] `cce advise` -- recommendations engine

## Acknowledgements

Idea and voice-spec: [Mike Bailey](https://failmode.com)
([@mbailey](https://github.com/mbailey)) -- including the $46k of
his own session data we validated against. Research, prototype,
write-up: Cora 7. A "How this got built" page is forthcoming -- this
project is transparent about its AI-pair-programming origin.

## License

[MIT](LICENSE).
