token-cost-tracker-plus

Built on affaan-m/ECC by @affaan-m (249,751 stars, MIT). All credit for the original idea to them. This fork improves and repackages it; upstream license preserved in UPSTREAM_LICENSE.

A Claude Code skill that reads local token use, cost, and budget data without changing your database.

Built for developers who use a trusted local cost tracker and want quick answers inside Claude Code.

💡 Why

Claude Code use can be hard to track across projects and sessions.

This skill turns a local SQLite log into clear cost and token reports.

It can break usage down by project, tool, session, model, or date.

Your data stays on your machine. The skill only reads the database.

⚡ Install

mkdir -p ~/.claude/skills/cost-tracking && curl -fsSL https://raw.githubusercontent.com/YOUR_GITHUB_NAME/token-cost-tracker-plus/main/skill/SKILL.md -o ~/.claude/skills/cost-tracking/SKILL.md

Replace YOUR_GITHUB_NAME with the GitHub account that hosts this repo.

You also need:

• Claude Code
• sqlite3
• A trusted tracker that writes data to ~/.claude-cost-tracker/usage.db

The skill will not create the database or install a tracking hook.

🧭 Usage

Ask Claude Code a plain question:

How much did I spend today, and which project cost the most?

Claude will first check SQLite, the database, its tables, and the timestamp format. It will then return a report like:

Time zone: local time
Today: $<tracked total>
Top project: <project name>
Tracked cost may differ from your final bill.

Other useful prompts include:

Show my token totals.
Compare today with yesterday.
List my ten most recent sessions.
Show cost by tool for the last seven days.
Am I over my $20 monthly budget?
Export recent usage as CSV.

The skill uses only columns found in your real database. Missing or blank groups are shown as Unknown when useful. Full session IDs stay hidden unless you ask for them.

🔧 What we changed vs upstream

• Rewritten from Japanese into clearer, more concise English with more explicit trigger examples.
• Adds stronger privacy and safety rules, including local-only processing, no database mutation, masked session IDs, and a warning that tracked cost may differ from the final bill.
• Adds setup failure handling for missing SQLite, unreadable files, and absent databases without creating or changing anything.
• Adds mandatory schema inspection and guidance for varying tables, columns, null values, and missing cost_usd.
• Adds timezone and timestamp-format checks to prevent inaccurate daily cost reports near midnight.

📄 License

Released under the MIT License.

The upstream MIT license and credit are preserved in UPSTREAM_LICENSE.