Cost Tracking

Credit: This skill comes from community PR #1304 by MayurBhavsar.

Use this skill to read Claude Code cost and usage data from a local SQLite database.

The normal database path is:

~/.claude-cost-tracker/usage.db

This skill only reads local data. Do not send data outside the computer. Do not add tracking, logs, web calls, or other data collection.

When to Use

Use this skill when the user asks:

• How much did I spend?
• What did this session cost?
• How many tokens did I use?
• Am I over my budget?
• Which project, tool, model, or session costs the most?
• How does today compare with yesterday?
• What is my recent cost trend?
• Can I export recent use as CSV?

First Checks

Check for SQLite and the database:

command -v sqlite3 >/dev/null && echo "sqlite3 found" || echo "sqlite3 missing"
test -f "$HOME/.claude-cost-tracker/usage.db" && echo "Database found" || echo "Database not found"

If SQLite is missing, say that it is needed to read the file.

If the database is missing:

1. Do not make fake usage data.
2. Say that local cost tracking is not set up.
3. Suggest a trusted local cost tracker.
4. Do not install a hook or plug-in unless the user asks.
5. Do not suggest code that sends usage data to the web.

Check the Data Shape

Trackers may use different table and column names. Check the real shape before you run a report:

sqlite3 -readonly "$HOME/.claude-cost-tracker/usage.db" ".tables"
sqlite3 -readonly "$HOME/.claude-cost-tracker/usage.db" "PRAGMA table_info(usage);"

Do not assume the table is named usage. If it has another name, use that name.

A common usage table has one row for each model event or tool call:

Use only columns that exist.

If cost_usd exists, use it. Do not work out the cost from token counts. Model and cache prices can change. The saved row cost should be the main source.

If cost_usd does not exist, report token use only. Explain that exact cost is not stored. Do not guess the price.

Safe Query Rules

• Open the database in read-only mode.
• Never change, delete, or add rows.
• Do not print full session IDs unless the user asks. A short prefix is often enough.
• Treat project names and session IDs as private data.
• Use COALESCE so missing values do not break totals.
• Say when key values are missing or NULL.
• Check how timestamps are stored before using date filters.
• State whether dates use UTC or local time.
• Do not place raw user text inside SQL.
• Use a fixed limit for row lists and exports.
• If the database is locked or damaged, report the error. Do not try to repair it unless the user asks.
• If there are no rows, say that no tracked use was found.

The examples below use the common usage table and column names. Change them only after checking the real data shape.

Report Examples

Quick Summary

sqlite3 -readonly "$HOME/.claude-cost-tracker/usage.db" "
  SELECT
    'Today: \$' ||
      ROUND(COALESCE(SUM(
        CASE WHEN date(timestamp, 'localtime') = date('now', 'localtime')
        THEN COALESCE(cost_usd, 0) ELSE 0 END
      ), 0), 4) ||
    ' | Total: \$' ||
      ROUND(COALESCE(SUM(COALESCE(cost_usd, 0)), 0), 4) ||
    ' | Rows: ' || COUNT(*) ||
    ' | Sessions: ' || COUNT(DISTINCT session_id)
  FROM usage;
"

Today and Yesterday

sqlite3 -readonly -header -column "$HOME/.claude-cost-tracker/usage.db" "
  SELECT
    date(timestamp, 'localtime') AS day,
    ROUND(SUM(COALESCE(cost_usd, 0)), 4) AS cost_usd,
    COUNT(*) AS rows
  FROM usage
  WHERE date(timestamp, 'localtime') IN (
    date('now', 'localtime'),
    date('now', 'localtime', '-1 day')
  )
  GROUP BY day
  ORDER BY day DESC;
"

Cost by Project

sqlite3 -readonly -header -column "$HOME/.claude-cost-tracker/usage.db" "
  SELECT
    COALESCE(project, '(not set)') AS project,
    ROUND(SUM(COALESCE(cost_usd, 0)), 4) AS cost_usd,
    COUNT(*) AS rows
  FROM usage
  GROUP BY project
  ORDER BY cost_usd DESC
  LIMIT 20;
"

Cost by Tool

sqlite3 -readonly -header -column "$HOME/.claude-cost-tracker/usage.db" "
  SELECT
    COALESCE(tool_name, '(not set)') AS tool,
    ROUND(SUM(COALESCE(cost_usd, 0)), 4) AS cost_usd,
    COUNT(*) AS rows
  FROM usage
  GROUP BY tool_name
  ORDER BY cost_usd DESC
  LIMIT 20;
"

Last Seven Days

sqlite3 -readonly -header -column "$HOME/.claude-cost-tracker/usage.db" "
  SELECT
    date(timestamp, 'localtime') AS day,
    ROUND(SUM(COALESCE(cost_usd, 0)), 4) AS cost_usd,
    COUNT(*) AS rows
  FROM usage
  WHERE datetime(timestamp) >= datetime('now', '-7 days')
  GROUP BY day
  ORDER BY day DESC;
"

Recent Sessions

sqlite3 -readonly -header -column "$HOME/.claude-cost-tracker/usage.db" "
  SELECT
    substr(COALESCE(session_id, '(not set)'), 1, 12) AS session,
    MIN(timestamp) AS started,
    MAX(timestamp) AS ended,
    ROUND(SUM(COALESCE(cost_usd, 0)), 4) AS cost_usd,
    COUNT(*) AS rows
  FROM usage
  GROUP BY session_id
  ORDER BY started DESC
  LIMIT 10;
"

Token Totals

Use this only when the token columns exist:

sqlite3 -readonly -header -column "$HOME/.claude-cost-tracker/usage.db" "
  SELECT
    SUM(COALESCE(input_tokens, 0)) AS input_tokens,
    SUM(COALESCE(output_tokens, 0)) AS output_tokens,
    SUM(COALESCE(input_tokens, 0) + COALESCE(output_tokens, 0)) AS total_tokens
  FROM usage;
"

Small CSV Export

Ask for the date range if the user did not give one. Keep the export small.

sqlite3 -readonly -header -csv "$HOME/.claude-cost-tracker/usage.db" "
  SELECT
    timestamp,
    project,
    tool_name,
    input_tokens,
    output_tokens,
    cost_usd,
    model
  FROM usage
  WHERE datetime(timestamp) >= datetime('now', '-7 days')
  ORDER BY timestamp DESC
  LIMIT 10000;
" > cost-usage-last-7-days.csv

Tell the user where the file was saved. Do not include full session IDs unless they ask.

Budget Checks

If the user gives a budget, compare it with the matching time range.

Report:

• The budget
• The amount spent
• The amount left
• The percent used
• The date range and time zone
• Whether the user is over budget

Do not treat a budget as saved unless the database has a clear budget table or column.

What to Report

A full report should include:

1. Today’s spend.
2. Yesterday’s spend.
3. The change from yesterday, when both days have data.
4. Total spend in the tracked database.
5. The top projects by cost.
6. The top tools by cost.
7. Session count and mean cost per session, when session IDs exist.
8. The date range and time zone used.
9. Any missing fields or gaps that may make the report less exact.

Use four digits after the decimal for costs under $1. Use two digits for larger costs.

Do not call a row a model call until the table proves that it is one. Some trackers also save tool events. Use the word “row” or “event” when unsure.

Concrete Usage Example

User:

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

Steps:

1. Check that SQLite and the database exist.
2. Read the table shape.
3. Check the timestamp form and time zone.
4. Sum cost_usd for the last seven days.
5. Group the same rows by project.
6. Show the top project and its share of the week’s cost.

Example reply:

You spent $2.1843 in the last 7 days, using local time.

The top project was `shop-app` at $1.3021. That was 59.6% of the total.

The database had 184 rows across 9 sessions. Two rows had no project name, so I grouped them as `(not set)`.

Do Not

• Do not guess costs when cost_usd is present.
• Do not use live model prices in the report.
• Do not assume the database or table exists.
• Do not run an open-ended SELECT * on a large table.
• Do not change the database.
• Do not hide missing or bad data.
• Do not install unreviewed hooks or plug-ins.
• Do not send local cost data to any outside service.
• Do not add analytics, telemetry, or web calls.

Related Skills

• /cost-report: A command-style report from the same database.
• cost-aware-llm-pipeline: Plans model use and budgets.
• token-budget-advisor: Plans token and context limits.
• strategic-compact: Cuts repeat token use by making context smaller.