cost-tracking

name	cost-tracking
description	Track and report AI model token usage, spending, and budgets from a local cost-tracking database.
origin	harness
workloads	["finops","ai"]

Cost Tracking

Use this skill to analyze AI model cost and usage history from a local SQLite database. It is intended for users who already have a cost-tracking hook or plugin writing usage rows to a local database.

When to Use

• The user asks "how much have I spent?", "what did this session cost?", or "what is my token usage?"
• The user mentions budgets, spending limits, overruns, or cost controls.
• The user wants a cost breakdown by project, tool, session, model, or date.
• The user wants to compare today against yesterday or inspect a recent trend.
• The user asks for a CSV export of recent usage records.

How It Works

First verify prerequisites:

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

If the database is missing, do not fabricate usage data. Tell the user that cost tracking is not configured and suggest installing or enabling a trusted local cost-tracking hook/plugin.

The expected usage table usually contains one row per tool call or model interaction. Column names vary by tracker, but common columns are:

Column	Meaning
timestamp	ISO timestamp for the usage event
project	Project or repository name
tool_name	Tool or event name
input_tokens	Input token count, when recorded
output_tokens	Output token count, when recorded
cost_usd	Precomputed cost in USD
session_id	Session identifier
model	Model used for the event

Prefer cost_usd over hand-calculating pricing. Model prices and cache pricing change over time, and the tracker should be the source of truth for how each row was priced.

Examples

Quick Summary

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

Cost By Project

sqlite3 -header -column ~/.cost-tracker/usage.db "
  SELECT project, ROUND(SUM(cost_usd), 4) AS cost, COUNT(*) AS calls
  FROM usage
  GROUP BY project
  ORDER BY cost DESC;
"

Cost By Tool

sqlite3 -header -column ~/.cost-tracker/usage.db "
  SELECT tool_name, ROUND(SUM(cost_usd), 4) AS cost, COUNT(*) AS calls
  FROM usage
  GROUP BY tool_name
  ORDER BY cost DESC;
"

Last Seven Days

sqlite3 -header -column ~/.cost-tracker/usage.db "
  SELECT date(timestamp) AS date, ROUND(SUM(cost_usd), 4) AS cost, COUNT(*) AS calls
  FROM usage
  WHERE date(timestamp) >= date('now', '-7 days')
  GROUP BY date(timestamp)
  ORDER BY date DESC;
"

Session Drilldown

sqlite3 -header -column ~/.cost-tracker/usage.db "
  SELECT session_id,
    MIN(timestamp) AS started,
    MAX(timestamp) AS ended,
    ROUND(SUM(cost_usd), 4) AS cost,
    COUNT(*) AS calls
  FROM usage
  GROUP BY session_id
  ORDER BY started DESC
  LIMIT 10;
"

Cost By Model

sqlite3 -header -column ~/.cost-tracker/usage.db "
  SELECT model, ROUND(SUM(cost_usd), 4) AS cost, SUM(input_tokens) AS in_tokens, SUM(output_tokens) AS out_tokens
  FROM usage
  GROUP BY model
  ORDER BY cost DESC;
"

Reporting Guidance

When presenting cost data, include:

1. Today's spend and yesterday comparison.
2. Total spend across the tracked database.
3. Top projects ranked by cost.
4. Top tools/models ranked by cost.
5. Session count and average cost per session when enough data exists.

For small amounts, format currency with four decimal places. For larger amounts, two decimals are enough.

Anti-Patterns

• Do not estimate costs from raw token counts when cost_usd is present.
• Do not assume the database exists without checking.
• Do not run unbounded SELECT * exports on large databases.
• Do not hard-code current model pricing in user-facing answers.
• Do not recommend installing unreviewed hooks or plugins that execute arbitrary code.

Related Skills

• context-budget — token usage analysis and context optimization
• strategic-compact — context compaction to reduce repeated token spend
• agentic-engineering — cost discipline in agent-driven workflows